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Chapter 1 


Introduction 


Welcome to the SunCore graphics package and its Programmer’s Reference Manual. Sun 
Microsystems offers a comprehensive package of engineering graphics software providing the 
underlying support for interactive graphics applications programs. The SunCore software is an 
implementation of the ACM Core graphics specification , plus extensions. SunCore is imple¬ 
mented to level 3C of the ACM Core specification for output primitives, and to level 2 of the 
ACM Core specification for input primitives. 

Extensions to the Core include textured polygon fill algorithms, raster primitives, raaterop attri¬ 
butes, shaded surface polygon rendering, and hidden surface elimination. 

This graphics package supports both the high resolution monochrome bitmap displays and the 
Sun color displays. Device-dependent routines support all these displays under SunCore. 

NOTE that this manual is a reference manual for the SunCore graphics package. It is not a 
tutorial for the programmer without knowledge of graphics principles. It assumes that the 
reader is familiar with the concepts of graphics, and has some familiarity with the ACM Core 
specification. Those who are new to graphics should consult one of the publications listed in 
further reading at the end of this chapter. 


Where to Start 

If you are an applications programmer who is familiar with the ACM Core specification, but are 
new to SunCore, it is recommended that you read appendix A in order to become familiar 
with the areas where SunCore deviates from and provides extensions to the ACM Core 
specification. 

Note that SunCore supports the ACM Core output level 3C, that is, dynamic output is sup¬ 
ported, including two and three-dimensional translation, scaling, and rotation. SunCore sup¬ 
ports the ACM Core input level 2, that is, synchronous input, including the PICK device. Sun¬ 
Core supports dimension level 2, that is, three-dimensional operations. 


1*1« Overview anci Terminology 

The objective of a graphics application program is drawing pictures and text on some display 
device, be it an ephemeral display device such as TV monitor or terminal, or a hard copy device 
such as a plotter or printer. 

* As defined in Computer Graphics, the ACM SIGGRAPH Quarterly, Volume 13, #3, August 1979. 
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There is a need for a device-independent way of representing graphics images in the computer, 
fti) H having a collection of software routines map the device-independent representations into 
the physical representations that the output device can handle. SunCore is an implementation 
of one of the ‘‘standard” packages of graphics software that have appeared recently. This sec¬ 
tion introduces some of the terminology of SunCore. This terminology is used throughout this 
manual. It is somewhat easier to describe the terminology from the point of view of the physi¬ 
cal device working backwards to the application program, rather than starting at the software 
and working out to the device. 

There are two quite distinct points of view for looking at a system running a graphics applicap 
tion: 

• The physical device (monitor, printer, and so on) on which the final pictures appear, and 

• The internal world which the programmer uses to describe the pictures, and which (because of 
SunCore) is independent of the physical device. 

A view eurface is a physical surface on which the finsd picture appears. 

There are two interdependent sets of coordinate systems in use in the graphics package: 

World Coordinatet 

is a coordinate system which is device-independent. The applications programmer con¬ 
structs all graphical objects in terms of world coordinates. 

Normalized Device Coordinates 

(often abbreviated to NDC) is a fixed coordinate system which is independent of physical 
output devices. World coordinates are transformed to normalised device coordinates for 
clipping and other operations. Each physical output device driver then transforms from 
normalised device coordinates to the physical device coordinates for each view surface. 

A viewport is a repon of NDC space which the programmer selects and on which the pictures 
will appear. 

It is the job of the viewing transformations to perform the correct mapping between world coor¬ 
dinates and normalised device coordinates. 

A window is a region defined in world coordinates within which the images that the application 
program defines appear. The selection of the coordinates for the window are arbitrary — the 
graphics package maps the window into the viewport. 

In two dimensions, the transformation from the window to the viewport is a relatively straight¬ 
forward process. In three dimensions, another level of complexity is introduced with the notion 
of a view plane which is positioned arbitrarily in world coordinates. 

An outpvt primitive, or often just & primitive, is a part of a picture (such as a line or a character 
string). The appearance of primitives (such as solid or dotted lines) is determined by primitive 
attributes. A primitive attribute ’is a general characteristic of an output primitive, and affects the 
appearance of that primitive. Examples of primitive attributes are color, linestyle, and 
linewidth. 

Each output primitive may be assigned a name, called the pick-id, which is used to identify that 
primitive when an input operation (such as pointing at the primitive with the mouse) is applied. 

The Current Position is a SunCore system value that defines the current location for drawing. 
At startup time, the Current Position is set to the origin of the world coordinate system. Func¬ 
tions that create output primitives (move, line, and so on) can alter the Current Position. 

Output primitives are collected together in segments. A segment defines an image which is a 
part of thp picture on a view surface. 
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Segments are divided into two classes, namely: temporary and retained. A retained segment has 
a name, and can have segment attributes associated with it. A temporary segment is nameless, 
and furthermore, the image that a temporary segment defines only remains visible as long as 
information is only being added to the view surface. As soon as a new frame action (one which 
repaints view surface) occurs, the temporary segment’s image disappears from the view surface. 

Each retained segment has one static attribute, its image transformation type. The value of 
this attribute can be none, tramlatable, or /ron«/orma6k. Translatable and transformable 
retained segments can be translated or transformed in either two or three dimensions. 

Segments also have dynamic attributes. The visibility and highlighting attributes control the 
appearance of the image. The detectability attribute determines if the segment can be detected 
by the pick device. Dynamic attributes for translatable and transformable segments include the 
segment’s image transformation. Depending on the image transformation type, the image 
transformation may contain translation, rotation, and scaling components. 

A viewing operation is an operation that maps positions in world coordinates to positions in nor¬ 
malised device coordinates. The viewing operation also determines the portion of the world 
coordinate space that is visible if window clipping or depth clipping is enabled. 

The applications program can obtain user interaction by means of input primitives, which pro¬ 
vide facilities for pointing at objects, entering data from the keyboard, and causing events. 


I. 1.1. Basics of Drawing Pictures 

The general sequence of actions that an application program goes through to create a picture on 
a device is this: 

1. /niVia/tre SunCore. 

2. Initialize a view surface upon which the picture will be drawn. 

3. Select a view surface upon which the picture will be drawn. 

4. Specify the viewing operation parameters (sises of windows in world coordinates, size of 
viewport, and so on). 

6. Set an image transformation type. 

0. Create a segment. The created segment becomes the currently open segment until it is 
closed. 

7. Set attributes for the segment, if required. 

8. Draw objects in the segment using output primitives. 

9. Close the segment. 

10. Repeat steps 4 through 9 as often as required, for as many segments as needed to build the 
picture. 

II. Apply image transformations (translation, scaling, and rotation) to a given segment, to 
achieve the required picture on the display device. 

12. Deselect the view surface. 

13. Terminate SunCore. 

In providing the application, programmer with the capabilities needed to draw pictures, Sun¬ 
Core breaks the interface into six functional areas: 

Control 

directs the major actions of SunCore, such as startup, shutdown, selection and deselection 


Revision E of 7 January 1984 


1-3 



Introduction 


SunCore Reference Manual 


of view surfaces^ and so on. 

Segment* 

control the creation, closing, and removal of segments. Segments are then used to collect 
sets of: 

Output Function* 

also known as output primitives, which describe the drawing of lines and line sequences, 
shaded regions, text, and marken. 

Attribute* 

control the way in which output primitives actually appear in the final image (solid or dot¬ 
ted lines, for instance). 

Tramfofmation* 

control the major appearances of pictures, such as orientation (rotation), scaling, and trans¬ 
lation. Transformations also control projection type and clipping. 

Input Fijipction* 

handle the interaction with the user via the keyboard and the mouse. 

1.2. Getting Started With SunCore 

This section provides a very simple example of a SunCore application program. The program 
draws a martini glass on the screen. This program demonstrates the use of: 

• Creating a temporary segment (see Segmentation and Naming), 

• Moving to an absolute position (see Output Primitives), 

• Using the polyline drawing routines (see Output Primitives), 

• Using the absolute line drawing routines (see Output Primitives), 

The annotated code of gla**.c is shown below, followed by the cc compiler call used to create 
the executable program. 

The fir*t thing in the program is an include statement to get the definition* of conatant*: 

^include <U8ercore.h> 

Then there are the definition* of the relative points for the polyline /unction to draw the gla**: 

static float glassdx[] =* {-10.0,9.0,0.0,-14.0,30.0,-14.0,0.0,9.0,-10.0}; 
static float glassdyl j = {0.0,1.0,19.0,15.0,0.0,-15,0,-19.0,-1.0,0.0}; 
int bwldd(); /* Device driver name for Sun-1 Monochrome */ 

/* display — see appendix B for detail* */ 
struct vwsurf vwsurf = DEPAULT_VWSURF(bwldd); 

Then comes the main program with some initia/iration code: 
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main() 

{ 


/* Pint initialize the SunCore Package */ 
if (initialize_core(BASIC, NOINPUT, TWOD)) 
exit(l); 

/* Elements of vwsurf may be set up here */ 
/* See Appendix B for details */ 


/* Then initialize the monochrome display */ 
if (initialite_vicw_surface(&Twsurf, FALSE)) 
exit(2); 

/♦ Then we must select that view surface *f 
if (8elect_view_8urface(&vws\urf)) 
exit(3); 

/* Then define the limits of the viewport */ 
8et_vie'wport_2(0.125, 0.875, 0.125, 0.75); 

/* Then set a convenient window */ 
8et_window(-50.0, 60.0, -10.0, 80.0); 

/* Create a temporary segment */ 
createjtemporsffy_8egment(); 

Here is the actual code that draws the picture: 

/* Now move to our origin point ♦/ 
movc_ab8_2(0.0, 0.0); 

/* And draw the outline of the glass */ 
polylinejel_2(gla88^, glassdy, 9); 

/* Then move to draw the liquid surface */ 
move_rel_2(-12.0, 33.0); 

/* Draw the liquid surface */ 

Hne_reL2(24.0, 0.0); 


Finally, Use close things and exit the program: 


} 


/* Now close the segment ♦/ 
cIo8e_temporary_8egment(); 

f* Wait for 10 seconds .... */ 


8leep(10); 


/* Before closing the view surface 
deseleet^view j5urface( fcvwsurf); 

/* and closing down SunCore */ 


temiinate_core(); 


*/ 


Now we compile this program using the C compiler: 

% cc g!a88.c —Icoi^e -Isunwlndow —Ipixreci —Im 

In the above example, the options: 

—Icore selects the SunCore run-time library from fusr/lib/libcore.a, 
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—Isunwindow selects the window system library, 

—Ipixrect selects the pixrect library, 

—Im selects the correct math library. 

When the compilation is complete, the final program is in the file a.out and may be run by typ¬ 
ing its name. 

This is a very simple example, using the bare minimum of SunCopo’s capabilities. There are 
many improvements that could be made, such as adding an olive on a cocktail stick and so on. 
The Programming Examples section of this manual will cover other areas of the graphics pack¬ 
age. 


1.3. The SunCore Lint Library 

SunCore provides a lint library which provides t 3 rpe checking beyond the capabilities of the C 
compiler. For example, you could use the SunCopo lint library to check the martini-glass 
drawing program with command like this: 

% lint glass.c -Isuncore 

but note that the error messages that lint generates are mostly w^nings, and may not neces¬ 
sarily have any effect on the operation of the program. For a detailed explanation of lintf see 
the lint manual in the Programming Tools manual. 

1.4. The Coordinate Systems 

Applications programs which draw pictures using SunCore communicate in world coordinates. 
World coordinates are a device-independent, two or three-dimensional, Cartesian coordinate sy^ 
tern for describing objects. Output primitives are given to SunCore routines in World Coordi¬ 
nates (WC). However, if the world_coordinate matrix is used, SunCore concatenates this 
matrix with the view transform so that output primitives are first transformed by this matrix 
from ‘model* or ‘object’ coordinates to world coordinates. This means that the user can supply 
primitives in ‘model’ coordinates, each model or object being moved into world coordinates 
according to the current world_coordinate_matrix. 

In three dimensions, the user tnay choose to use right-handed or left-handed world coordinates. 
In a right-handed System, if (fop example) the x coordinate increases to the right and the y coor¬ 
dinate increases upwarii, then the z coordinate increases towards the viewer. In the 
corresponding left-handed system, the * coordinate increases to the right, the y coordinate 
incresises upwards, and the r coordinate increases away from the viewer. 

The composite viewing transform is formed from the world_coordinate_matriz and the viewing 
parameters. SunCore routines transform the output primitives from world (or model) coordi¬ 
nates to Normalized Device Coordinates (NDC), which are a left-hand coordinate system 
bounded as follows: 

0.0 ^ X, g, z < 1.0 

Since current Sun view surfaces have four-to-three aspect ratios, the default normalized device 
coordinate space has the y extent bounded to 0.0 < y < 0.75. Primitives are stored in the 
Display List (also called the Pseudo Display File or PDF), in Normalized Device Coordinates. 
The user-specified window in world coordinates is mapped (and optionally clipped) to the user- 
specified viewport within normalized device coordinate space. The entire normalized device 
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coordiiiate space is then mapped to the selected physical view surfaces. 


1.5. Details of Using SunCore 

This section describes the details of creating applications programs to run with SunCore. 

1*5.1. Classification of Functional Capabilities 

The ACM Core specification defines levels of functional capability for a graphics package which 
implements the specification. The table below shows the classification. Terms such as BUF¬ 
FERED and DYNAMICA are defined as constants in the file usercore.h, discussed below. 

Table 1-1: Output Capabilities 


Functional Capability 

BASIC 

Output Capabilities 

BUFFERED DYNAMICA 

DYNAMICB 

DYNAMICC 

Output Primitives and 
Primitive Attributes. 

yes 

yes 

yes 

yes 

yes 

Viewing 

yes 

yes 

yes 

yes 

yes 

Control 

yes 

yes 

yes 

yes 

yes 

Temporary Segments 

yes 

yes 

yes 

yes 

yes 

Retained Segments 

no 

yes 

yes 

yes 

yes 

Highlighting Segment 
Attribute 

no 

yes 

yes 

yes 

yes 

Vieibilitg Segment 
Attribute 

no 

yes 

yes 

yes 

yes 

Image Transformation 
Segment Attribute 

no 

no 

yes 

yes 

yes 

Detectability Segment 

no 

* 

* 



Attribute 

yes 

yes 

yes 

yes 


♦ This feature is only available if input levels SYNCHRONOUS or COMPLETE are supported. 
Note that SunCore supports all output levels up to DYNAMICC. 
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Table 1-2: Input Capabilities 


Input Capabilities 

Functional Capability NOINPUT SYNCHRONOUS 

COMPLETE 

Device Initialization and Termination 

no 

yes 

yes 

Synchronous Interaction Functions 

no 

yes 

yes 

Echo Control 

no 

yes 

yes 

Explicit Enable or Disable 

no 

no 

yes 

Event Queue Management 

no 

no 

yes 

Sampled Device Functions 

no 

no 

yes 

Associations 

no 

no 

yes 


Note that SunCore supports up to the SYNCHRONOUS input level. 


Table 1-3: Dimension Levels Supported 


Dimension Levels Supported 


Functional Capability 

TWOD 

THREED 

Two Dimensional Primitives, 
Attributes, and Viewing. 

yes 

yes 

Three Dimensional Primitives, 
Attributes, and Viewing. 

no 

yes 


Note that SunCore supports the THREED dimension level. 

1.5.2. Error Reporting 

SunCore performs consistency checks on arguments passed to its various routines. Any time 
an error is detected, the name of the routine which raised the error condition and the text of 
the error message are printed on the standard error (stderr). 

All SunCore interfaces are functiona that return a value. If a function completes successfully, 
it returns the value zero. If the function raises any error conditions, it returns a non-zero value. 
SunCore always identifies the name of the routine which raised the error condition. The ACM 
Core specification defines specific error numbers. These do not correspond to Sun Core’s error 
numbers in the current release. 
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1.5.3* Useful Constants in the usercore.h Include File 

The file utercore.h defines a collection of constants which the application programmer should 
use in lieu of hardwired constants in code. The constants are described here (but their values 
are not stated). 

Uteful Constants: 

TRUE A universal value denoting the truth value. 

FALSE A universal value denoting the false value. 

MAXVSURF The maximum number of view surfaces which may be initialized at any one time. 

Initiatization Constants. These constants describe the levels of the SunCore facilities which 
the application program will use. These constants should be used when calling the 
initialize^eore function. 

BASIC Denotes the basic output level. See the tables above for the classifications. 

BUFFERED Denotes the buffered output level. See the tables above for the classifications. 

DYNAMICA Indicates that the application package wishes to use two-dimensional translation 
facilities. See the tables above for the classifications. 

DYNAXQCB Indicates that the application package wishes to use two-dimensional scaling, rota¬ 
tion, and translation facilities. See the tables above for the classifications. 

DYNAMIOO Indicates that the application package wishes to use three-dimensional scaling, rota- 
' tion, and translation facilities. See the tables above for the classifications. 

NOINPUT Indicates that t^s application package will not use any input facilities. See the 
tables above for the classifications. 

SYNCHRONOUS 

Indicates that this application program will use synchronous input facilities. See the 
tables above for the classifications. 

COMPLETE SunCoro does not support this input level. See the tables above for the 
classifications. 

TWOD Indicates that the application package will only use two-dimensional functions. See 
the tables above for the classifications. 

THREE3> Indicates that the application package will use both two-dimensional and three- 
dimensional functions. See the tables above for the classifications. 

Character Qualitf/ Constants. These constants should be used when calling the set^ckarprecision 
function. 

STRINO Denotes low quality text. 

CHARACTER 

Denotes medium quality text. 

Transform Constants. These constants should be used when calling the set_profection and 
set_eoordinatejsystem_type functions. 

PARALLEL Value to indicate parallel projection. 

PERSPECTIVE 

Value to indicate perspective projection. 
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RIGHT Value to indicate right-handed world coordinate system. 

LE^T Value to indicate left-handed world coordinate system. 

Image Tranaformation Type Conatanta. These constants are used when calling the 
aetjimagejtranaformationJtype and aet_jegmentjimageJlranaformationJtifpe functions. 

NONE Indicates a retained segment which cannot be transformed. 

XLATE2 Indicates a retained segment which may be translated in two dimensions. 

XFORM2 Indicates a retained segment which may be fully translated, scaled, and rotated, in 
two dimensions. 

XLATE3 Indicates a retained segment which may be translated in three dimensions. 

XFORM3 Indicates a retained segment which may be fully translated, scaled, and rotated, in 
three dimensions. 

Line Style Conatanta. These constants should be used when calling the aetjlmeotyle attribute 
for output primitives. 

SOLID Solid line. 

DOTTED Dotted line. 

DASHES) Dashed line. 

DOTDASHED 

Dashed and dotted line. 

Text Font Selection Conatanta. These constants should be used when calling aet^ont. 

ROMAN For character precision, a Roman font; for atring precision, a raster font. 

GREEK For character precision, a Greek font; for atring precision, the default raster font. 

SCRIPT For character precision, a Script font; for atring precision, a small raster font. 

OLDENGLISH 

For character precision, an Old English font; for atring precision, equivalent to 
ROMAN. 

STICK For character precision, a stick font; for atring precision, equivalent to GREEK. 
SYMBOLS For character precision, a set of symbols; for atring precision, equivalent to SCRIPT. 

Input Device Conatanta. These constants should be used when calling the initiaUze_device and 
terminatejievice functions and other input functions. 

PICK The Pick device. The mouse in SunCore. 

KEYBOARD 

The Keyboard device. 

STROKE The freehand stroke device. The mouse in SunCore. 

LOCATOR The Locator device. The mouse in SunCore. 

VALUATOR 

The Valuator device. The mouse in SunCore. 

BUTTON The Button device. The mouse in SunCore. 
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Ra^terop Conatantt. These constants should be used when calling the aetjraaterop function. 
NORMAL Indicates normal copy mode. 

XORROP Indicates bitwise exclusive or of source and destination. 

ORROP Indicates bitwise or of source and destination. 

Polygon Rendering Style Conatanta. These constants should be \ised when calling the 
aet_polygon_interior^atffie and aet ahading parametera functions. 

PLAIN Indicates area fill with the color indicated by the fill index primitive attribute. 

SHADED Indicates shading according to the current shading parameters (for 3-D polygons 

only). 

CONSTANT Indicates constant user-specified shade. 

QOURAUD Indicates Gouraud shading. 

PHONG Indicates Phong shading. 


I. 6. Further Reading 

J. D. Foley and A. Van Dam: 

Fundamentals of Interactive Computer Graphics, Addison-Wesley, 1982. 

W. M. Newman and R. F. Sproull: 

Prineiplea of Interactive Computer Graphiea (Snd edition), McGraw-Hill, 1979. 

ACM SIGGRAPH: 

Conference Proceedings. 

IEEE Computer Graphics and Applications Magazine 
Computer Graphics ACM SIGGRAPH Quarterly, Vol 13, #3, August 1979 
Status Report of the Graphics Standards Planning Committee. 

ACM Computing Surveys, Vol 10, #4, Dec 1978 
Special Issue on Graphic Standards. 

Computer Graphics World, Vol 5, #8, August 1982 
The SIGGRAPH Core System Today. 
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The Sun Core graphics package provides several functions for controlling the system. These 
functions are discussed here, and the sections and subsections which follow describe the indivi¬ 
dual functions in detail. 

InitiaUzation and termination 

of SunCore provide for the initialization of the package to a specific and predetermined 
state, and for closing it down when the applications program has finished using the graphics 
package. 

View surface control 

provides for the initialization, termination, and selection of view surfaces. A view surface 
must be initialized before it can be used. A view surface should be terminated when the 
applications package has finished with it. Functions are provided to add view surfaces to 
the set of selected view surfaces, and to remove view surfaces from that set. View surface 
names in SunCore are structures. The vwsurf structure is declared in uoereore.h and is 
described in appendix B. SunCore supports several view surfaces to date; see appendix B 
for details of view surfaces. 

Picture change control 

provides for the ‘‘batching” of changes to dynamic segment attributes so that the applica¬ 
tion program may force the simultaneous occurrence of a group of changes. 

Frame control 

denotes the function called new_frame, which clears the view surface and redraws all seg¬ 
ments except temporary segments. 

Error handling 

is that part of SunCore concerned with reporting errors to the application program. 

2.1. Initialization and Termination 

There are two functions provided for initializing and terminating SunCore. The application 
program should call initialize_eore before making any other calls upon the graphics system. 
terminate^eore should be the last call to SunCore before the application program itself is 
finished. 
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2.1.1. initialize_core — Initialize the SunCore System 

initialize_eore initializes the Core graphics package to a known state. 

initialize_core(outputjlevel, inputjevel, dimension) 

int outputjevel; f* SunCore Level for Output */ 

/* BASIC, BUFFERED, DYNAMICA */ 

/* DYNAMICB, DYNAMICC */ 
int input level; /* SunCore Level for Input ♦/ 

/* NOINPUT, SYNCHRONOUS, COMPLETE */ 
int dimension; /* Number of Dimensions Required */ 

/* TWOD, THREED ♦/ 

SunCore supports up to output level DYNAMICC of the ACM Core specification, up to input 
level SYNCHRONOUS of the ACM Core, and dimension level THREED of the ACM Core. 

Errors returned from tmtiaitze_core: 

• The SunCore system is already initialized. 

• The specified output level cannot be supported. 

• The specified input level cannot be supported. 

• The specified dimension cannot be supported. 

2.1.2. terminate_core — Close Down the SunCore System 

Urmmate_corc closes down the Core graphics package. 
terminate_core{ ) 


2.2. Initializing and Selecting View Surfaces 

View Bwface control provides for the initialization, termination, and selection of view surfaces. 
A view surface must be initialized before it can be used. A view surface should be terminated 
when the applications package has finished with it. Examples of view surfaces are the Sun color 
display and the Sun monochrome bitmap display. Functions provided in this category are: 
initi cJize_j;iew_» urface 

performs the functions required to gain access to a specified view surface. 
ter min a te_view^s urface 

terminates access to the specified view surface. 
selectjoiew_Burface 

adds the specified view surface to the set of selected view surfaces for output. 
deselect_view_surface 

removes the specified view surface from the set of selected view surfaces. 
inquire_selected_surfaces 

determines which view surfaces are currently selected (not yet implemented). 
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2.2.1. initialize_view_surface — Initialize a View Surface 

initialize_view_aurface initializes the Core package for a specific view surface. 

initialize_view_surface(surface_name, type) 

struct vwsurf *surface_name; /* See appendix B ♦/ 

int type; /* TRUE for hidden surface removal */ 

/* FALSE otherwise */ 

The turfacejname argument to the function specifies a physical view surface. View surface 
names in SunCore are structures. The vtvturf structure is defined in the usercore.k header file. 
Only color devices support hidden-surface removal. 

Errors returned from tnitialize_view_8urface: 

• The view surface specified by surface_jntme is already initialized. 

• The view surface specified by turfaee^name does not have any output device associated 
with it. 

• No other view surfaces can be initialized at this time. 

• The specified view surface does not support hidden surface removal. 


2.2.2. terminate_view_8urface — Close Down a View Surface 

terminate_vicv}_8itrfac« closes down the specified view surface. 

tenninate_view_8urface(8urfacejiiame) 

struct vwsurf ♦surface^name; /* See appendix B ♦/ 


Errors returned from terminatejiftew^aurface: 

• The view surface specified by ewface_name is not initialized. 


2.2.3. seleci;_yiew_8urface — Add View Surface to Selected Set 

telectjtnewjtw/aci adds a specified view surface to the list of selected view surfaces. 

8elect_view_surface(surface_name) 

struct vwsurf *surface_name; /* See appendix B */ 

A segment is only drawn on those view surfaces marked as “selected" at the time that the seg¬ 
ment is created. 

Errors returned from telectjifiewjturface: 

• A segment is open. 

• The view surface specified by »urfacc_name is not initialized. 

• The view surface specified by turfacejnamc is already selected. 

• The view surface specified by surfacc_namc cannot be selected. 
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242.4. deselect_view_surface — Remove View Surface from 
Selected Set 

dciehct_vitw_9urfacc removes a specified view surface from the list of selected view surfaces. 

deselect_view_surface(surface_name) 

struct vwsurf *surface_name; f* See appendix B *f 

Segments created after dctetect_vicw_$urface is called will not be drawn on the deselected view 
surface. 

Errors returned from de»ehct_vicu)_surfaer. 

• A segment is open. 

• The view surface specified by sur/ace^name is not selected. 


2.3. Batching of Updates 

SunCore provides the facility for the application program to indicate that a sequence of 
updates is being started, and the graphics package stacks up these picture changes until an 
end_btttcA_o/_updates function call indicates that the end of the sequence of updates has 
occurred. Picture changes or “updates” include dynamic segment attributes such as visibility, 
detectability, translate, rotate, and scale. 

2.3.1. begin_batch_of_update3 —: Indicate Start of a Batch of 
Updates 

begin_batch^of_updates indicates the beginning of a batch of updates to the picture. All 
modifications to dynamic attributes of segments between calls to begin_batch_of_updates and 
endJbateh_of_updates are saved up and executed simultaneously. 

bepn_batch_of_updates( ) 


Errors returned from beginJbatch_ofjapdates'. 

• There has been no tnd_batch_ofjupdates function call since the last 
begin_batch_of_updates function call. 


2.3.2. end_batch_of_updates — Indicate End of a Batch of 
Updates 

end_batch_ofjapdates indicates the end of a batch of updates. The batch of changes to dynamic 
attributes of segments is executed, 

end_batch_of_updates( ) 


Errors returned from end_batch_ofjapdates‘. 

• There has been no corresponding hegin_batcb_,of_‘updates function call. 
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2.4. Frame Control 


2.4.1. new_frame — Start New Frame Action for Selected View 
Surfaces 

new^rame starts new frame action for currently selected view surfaces. The view sirnface is 
cleared, and all visible retained segments are redrawn. 

new_frame() 


Errors returned from nevo_framer. 

• The set of currently selected view surfaces is empty. 


2.5* Error Control 



2.5.1. report_most_recent_error 

reportjmoitjreeent^jerror obtains a copy of the most recently detected error number. 

report_most_recent_error(error_number) 
int ♦error_number; 

A value of sero returned to errorjnumbcr indicates that there has been no error since the last 
call on rcport_most_recent_error. 


2.5.2. print_error 

To print the message associated with this errorjnumber on the standard error file (stderr), use 
the function call: 

print_error(”Your message”, error_uumber); 
int errorjaumber; 

where “Your message” is any character string that the user wants printed. The error message 
is printed on the line following ”Your message”. 

2.6. Drag Control (SunCore Extension) 


2.6.1. set_drag 

An additional function, set^drag, writes all output to the bitmap or color framebuffer with 
exclusive or’ing. 


Q 
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set_drag(inode) 

ini mode; /* FALSE — uses the ro«fcrop */ 

/* set b7 9ct_ra8terop */ 

/* TRUE = enable XOR’ing */ 

If dragging is enabled, all output to the device drivers is done with exclusive OR’s to the data 
in the displays. This feature makes dragging more convenient. For example, if you want to 
drag segment A across segment B, leaving segment B’s image unaffected, do the following 
sequence of operations: 

• Set A visibility off, 

• Set dragging on, 

• Set A visibility on, 

• Drag segment A to the desired location, 

• Set A visibility off, 

• Set dragging off, 

• Set A visibility on. 

See also: aet_raaterop. 




o 
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Viewing Operations and Coordinate Transforms 


Specifying a viewing operation may be thought of as specifying the arbitrary orientation of a 
synthetic camera. The resulting view of the object (the snapshot) can appear on one or more 
view surfaces. The viewing operations are provided for two reasons: 

1. To specify how much of the world coordinate space should be visible, and 

2. To specify a mathematical transformation between the world coordinate system and the nor* 
malized device coordinate system. 

A viewing operation is specified by a view volume that defines the portion of world coordinate 
space which is to be projected onto a view plane (also called a projection plane), and a rectangu¬ 
lar viewport in normalized device coordinate space to which the projected image will be 
mapped. The viewing operation is sufficiently general as to support both parallel and perspec¬ 
tive projections. The parallel projection includes the orthographic, axonometric, isometric, 
cavalier, and cabinet projections, as special cases. 

Once the camera model is specified via calls to tct_view_Tefercncc_pomt, set_vicw_plane_normal, 
and so on, a 4 X 4 view transform matrix is constructed. Then the process of generating an 
image on a view surface is: 

1. View-transforming the output primitives (using the view transform preceded by any model¬ 
ling transform the user has specified) to normalized device coordinates. 

2. Optional clipping to the window. 

3. Scale the output to map the window to the viewport. 

4. Optional image transformation as specified by dynamic segment attributes. 

5. Optional clipping to the viewport. 

6. Convert to device coordinates and draw the picture. 

3.1. Windows, View Volumes, and Clipping 

The window is the bounded portion of the view plane eontaining projected objects which will 
appear within the viewport on the view tur/ace. The view surface corresponds to the physical 
device on which the picture is drawn. The window is the logical region, specified in world coor¬ 
dinates, in which the image appears. 

Specifying a window involves defining a coordinate system for the view plane. The coordinate 
system for the view plane is called the UVW coordinate system, to distinguish it from the world 
coordinate system and the normalized device coordinate system, both of which are XYZ coordi¬ 
nate systems. 
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The origin of the UVW coordinate system is at the point where the line through the view refer¬ 
ence point parallel to the view plane normal vector intersects the view plane. In the default 
case, the view plane distance is zero, and so the view reference point lies in the view plane and 
is the origin of the UVW coordinate system. 

The direction of the V axis is determined from the view up vector. The view up vector is 
specified in world coordinates relative to the view reference point. 

The positive U axis of the UVW coordinate system is 90 degrees clockwise from the positive V 
axis, as viewed in the direction of the view plane normal vector. The positive U and V axes, 
together with the view plane normal vector, form a left handed coordinate system. The window 
is specified in terms of maximum and minimum uand u values (see the function). 

The diagram below shows the various components of the viewing system. 


Front Clipping Plant 



Figure 3-1: Components of Viewing System 
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3.2. Default Values of Viewing Operation Parameters 


Table 3-1; Default Values of Viewing Operation Parameters 


Parameter 

Viewing Operation Parameters 

Default Value 

View Reference Point 

(0,0,0) 

View Plane Normal 

(0,0,-l) 

View Distance 

0 

Front Distance 

0 

Back Distance 

1 

Type of Projection 

Par^let (0, 0, 1) (perpendicular to the UV plane) 

Window 

(0, 1, 0, 0.75) 

View Up Vector 

(0,1.0) 

Normalised Device 

0.0 < X,Z< 1.0 

Coordinate Space 

0.0 < y < 0.76 

Viewport 

(0.0, 1.0, 0.0, 0.75, 0.0, 1.0) 


Table 3-2: Default Values of Viewing Control Parameters 


Parameter 

Viewing Control Parameters 

Default Va/ue 

Window Clipping 

On 

Output Clipping 

Off 

Front Plane Clipping 

Off 

Back Plane Clipping 

Off 

World Coordinate System 

Right handed 
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Table 3-3: World Coordinate Matrix Parameters 


World Coordinate Matrix Parameters (Modelling Transform) 

Parameter _ Default Value __ 

1000 

World Coordinate Matrix q q j ^ (identity) 

000 1 


Table 3-4: Image Transformation Parameters 


Parameter 

Image Transformation Parameters 

Default Value 

SX, SY, SZ 

1, 1, 1 (no scaling) 

AX, AY, AZ 

0, 0, 0 (no rotation) 

TX, TY, TZ 

0, 0, 0 (no translation) 


3.3* Setting 3D Viewing Operation Parameters 

SunCore provides a number of functions for setting parameters of the viewing operations. 
There are a number of separate calls available for setting individual parameters, then there is a 
composite set viewing parameters function which sets all the viewing parameters in one fell 
swoop. The individual calls provided are summarised here and described in detail in the subsec¬ 
tions following. 
setjoiew_referen ce_jt oint 

Sets the view reference point in world coordinates. 

»et_view_plane_normal 

Defines a vector which determines the view plane, relative to the view reference point. 

9 et_view^dia tan ee 

Defines the view plane distance from the view reference point along the view plane normal 
vector. 

9€tjvieur_depth 

Defines the distance from the view reference point to the Trent' clipping plane (also known 
as the 'hither' or 'near' clipping plane) and the distance from the view reference point to the 
'back' clipping plane (also known as the 'yon' or 'far' clipping plane). 

9et_projeo(lion 

Selects perspective or parallel projection, and defines the center of projection (for PESISPEC- 
TIVE projection) or direction of projection (for PARALLEL projection). 

9et_vieu>_up_2, 9et_vicu}jup 

Establish the view up direction in the view plane for two or three-dimensional viewing. 
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ittjwindow 

Establishes the window boundaries in the view plane. 

9Ctjviewport_8f 8et_viewport_S 

Establish the viewport boundaries in normalized device coordinates for two or three- 
dimensional viewing. 
act viewin g p aramttert 

is a composite function which does all of the above functions at one time. 

None of the above calls have any effect until the next call upon the ereaUjretaineijtcgmcnt or 
ereate_temporary_ 9 CQment functions. 


3.3.1. set_view_reference_point — Establish Reference Point for 
"Viewing 

tct_,view_refeTtnee_point sets the view reference point in world coordinates. 

set^view_reference_point(x, y,») 

float X, y, z; /* x, y, and z coordinates */ 

X, y, and z are the coordinates of the view reference point. In the absence of a specified refers 
ence point, the default view reference point is (0, 0, 0). The new reference point does not take 
effect until a new segment is created. 


3.3.2. set_yiew__plane_nornial — Establish View Plane Normal 
Vector 

8Ct_vicw_plane_normal defines a vector relative to the view reference point, in world coordinates. 

set_view_plane_normal(dx_nonn, dyjiorm, dz_norm) 
float dx jiorm, dyjiorm, dz_norm; 

The view plane is perpendicul» to the view plane normal vector. In the absence of any infor¬ 
mation to the contrary, SunCore establishes the view plane normal vector as (0, 0, -1). The 
new vector does not take effect until a new segment is created. 

Errors returned from aetjoitwjplantjnormadr. 

• No view plane normal direction can be established because dxjnorm, dy_norm, and 
d 4 _n 0 rm are all zero. 


3.3.3. set_view_plane_di8tance — Establish View Plane Distance 

8ei_vicv>_plnnt_ditiancc establishes the view plane distance. 

8et^view_plane_di8tance(distance) 
float distance; 

8et_vieva_^lanc_di8tance establishes the view, or projection, plane. The view plane is perpendicu¬ 
lar to the view plane normal vector, and is dUtmce from the view reference point along the view 
plane normal vector. Distances are measured in world coordinate units from the view reference 
point. Positive values of diatance correspond to the direction of the view plane normal vector, 
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and negative values correspond to the opposite direction. In the absence of anj information to 
the contrary, diatanee is set to zero, which means that the viewing plane is located at the view 
reference point. 

3.3.4. set_projection — Select Projection Type 

aetjprojeciion selects the projection system for displaying. 

8et_projection(projection, dx_proj, dy_proj, dz_proj) 
int projection; /* Projection type */ 

/* PARALLEL; PERSPECTIVE */ 

float dx_proj, dy_proj, dz_proj; /* x, y, and z Deltas of Projection Point */ 

The arguments dzjproj, dyjproj, and dz_proj specify a world coordinate point relative to the 
view reference point. If projection is PARALLEL, objects project onto the view plane along lines 
parallel to the vector specified by dz_pro}, dy_proj, and dzjproj. If projection is PERSPECTIVE, 
{dxjproj, dyjproj, dzjproj) specify a point in world coordinates called the center of projection 
(often abbreviated to COP). Objects project onto the view plane along lines travelling towards 
this point. Thus the center of projection is the apex of a pyramid whose edges pass through the 
four corners of the view window. 

Errors re)>umed from atijprojection: 

• Thjp direction of projection cannot be established because dz, dy, and dz are all zero. Note 
thsft this error is only applicable if parallel projection was selected. 

3.3.5. set_view_up_2 — Establish 2D View Up Vector 

aet_viewjup_2 establishes a view up vector in two dimensions. This vector defines the direction 
of ‘up’ for the window in world coordinates. 

set_view_up_2(dx, dy) 

float dx, dy; f* dx and dy coordinates 

Errors returned from act_vizw_up_8: 

• The view up vector cannot be established because dz, and dy are both zero. 


3.3.6. set_view_up_3 — Establish 3D View Up Vector 

aet_view_up_S establishes a view up vector in three dimensions. 
set_view_up_3(dx_up, dy_up, dz_up) 

float dx_up, dy_up, dz_up; /* x, y, and z Deltas of View Up Vector */ 

The three arguments dx_up, dy_up, and dz_up establish a view up vector relative to the view 
reference point. The view up vector, when projected onto the view plane in the direction of the 
view plane normal vector, specifies the positive V-axis of the UVW coordinate system in the 
view plane. The U-axis is also in the view plane, such that the U-axis, the V-axis, and the view 
plane normal vector form a left handed coordinate system. The V-axis is vertical and the U- 
axis increases to the right when the view plane is mapped onto the view surface. 

SunCore establishes the default view up vector as (0, 1, 0), which means that the Y-axis is up. 
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If the view plane normal vector is parallel to the Y-axis, this does not work and so SunCore 
checks the view transforms for validity when creating a segment. SunCore may generate the 
error message: 

‘The current viewing specihcation is inconsistent’ 

Errors returned from «et_vieufjup_3: 

• No view plane normal direction can be established because dxjup, dyjnp, and dz_up are all 
Kero. 


3.3.7. set_ndc_space_2 — Establish Size of NDC Space 

eet_nde_»pace_8 defines the size of the Normalized Device Coordinate space which can be 
addressed on the view surface of all display devices available to the applications program and 
within which viewports may be established. 

8et_ndc_space_2(width, height) 
float width, height; 

Both width and height must be in the range of 0.0 to 1.0, and at least one of the parameters 
must have a value of 1.0. Normalized Device Coordinates range from 0.0 to width in the hor¬ 
izontal direction and from 0.0 to height in the vertical direction. The rectangle defined by this 
function is mapped to the viewable area of any display device available to the application pro¬ 
gram so that the entire rectangle is visible. Only uniform scaling of the rectangle is allowed; no 
changes can be made to the viewport aspect ratio. SunCore maximizes the usable area of the 
dislay and centers NDC space on each view surface. 

The default Normalized Device Coordinate specification is u7t(lfA=>1.0 and height=0.75. Either 
of the eet_nde_»paee_8 or setjnde^spaee^S (see below) functions may be used at most once per 
initialization of SunCore, and the Normalized Device Coordinate space established applies to 
all view surfaces which the application program might use. 

Ten SunCore functions require that Normalized Device Coordinate space be established before 
they complete execution. If Normalized Device Coordinate space has not been explicitly defined 
before any of these functions are executed, they implicitly define the Normalized Device Coordi¬ 
nate space using demult values. Functions which implicitly define Normalized Device Coordi¬ 
nate space ai^e: 

• initialize_device 

• initialize_gr6up 

• crettte_retained_$egment 

• create_ temper arp_zegment 

• »etjoiewport_B 

• eetjoiewpertjd 

• zet,jjie%Bing^ parameters 

• inquirej!oiewport_2 

• i»^otr«_v»ca^of/_^ 

• inquire viewing parameters 

The depth of Normalized Device Coordinate space is set to 0.0 if tet_ndc_zpace_2 is used in a 
three-dimensional implementation. 
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Errors returned from setjndcjipace^S: 

• tet_ndc_»pace_8 or 9 et_ndc_tpace_S has already been called since the system was initial¬ 
ized. 

• »et_ndcjtpace_2 or itt_ndejtpace_S has been called too late — the default values have 
already been defined implicitly. 

• A parameter is outside the range 0.0 to 1.0. 

• One of toidth or height must have a value of 1.0. 

• width or height has a value of 0.0. 


3.3.8. set_ndc_8pace_3 — Establish Size of NDC Space 

$et_ndc_space_S defines the size of the Normalized Device Coordinate space which can be 
addressed on the view surface of all display devices available to the applications program and 
within which viewports may be established. Three-dimensional Normalized Device Coordinate 
space is a rectangular parallelepiped lying within the Normalized Device Coordinate system. 
This coordinate system is always left-handed, with the ^axis increasing to the right, the y-axis 
increasing upwards, and the r-axis increasing away from the viewer. 

setjidcjipace_3(width, height, depth) 
float width, height, depth; 

All of the parameters width, height, and depth must be in the range of 0.0 to 1.0, and at least 
one of width or height must have a value of 1.0. Normalized Device Coordinates range from 0.0 
to width in the horizontal direction, from 0.0 to height in the vertical direction, and from 0.0 to 
depth in the direction away from the viewer. The rectangle of size width by height in the r«0 
plane of Normalized Device Coordinate space is mapped to the viewable area of any display dev¬ 
ice available to the application program so that the entire rectangle is visible. Only uniform 
scailing of the rectangle is allowed — no changes can be made to the viewport aspect ratio. 
SunCore maximizes the usable area of ihe display and centers NDC space on each view sur¬ 
face. 

The default ^Jormalized Device Coordinate specification is height=°0.75, and 

depth=l.O, Either of the 8et_ndc_space_S or set_nde_apaee_8 {see above) functions may be used 
at most once per initialization of SunCore, and the Normalized Device Coordinate space estar 
blished applies to all view surfaces which the application program might use. 

Ten SunCore functions require that Normalized Device Coordinate space be established before 
they complete execution. If Normalized Device Coordinate space has not been explicitly defined 
before any of these functions are executed, they implicitly define the Normalized Device Coordi¬ 
nate space using default values. Functions which implicitly define Normalized Device Coordi¬ 
nate space are: 

• initiaUze_deviee 

• initiaiize_group 

• create_retained_segment 

• createjtemporaryjiegment 

• 8et_viewport_8 

• eetjoiewportjS 
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• 9et_viemng^arametert 

• inquire_vietvport_B 

• inquireji>iewport_S 

• inquire viewing parameters 

Errors returned from set_nJe_epace_S: 

• eet_nde_$paee_ff or tet_nde^»paee_,S has already been called since the system was initial¬ 
ized. 

• set_jide_spaee^8 or *et_nde_»pace_S has been called too late — the default values have 
already been defined implicitly. 

• A parameter is outside the range 0.0 to 1.0. 

• One of width or height must have a value of 1.0. 

• width or height has a value of 0.0. 


3.3.9. setjwindow — Establish a Window in the View Plane 

9et_jpindow establishes a window, defined by four coordinates in the UV coordinate system, in 
the view plane. 

setjwindow(umin, umuc, vmin, vmax) 

float umin, umax; /* Left and Right sides of window */ 

float vmin, vmax; /* Bottom and Top of window */ 

SunCore establishes the default window as (0.0, 1.0, 0.0, 0.75). 

Errors returned from setjwindow: 

• umin is greater than or equal to umax, which means that the left side of the window is 
congruent with or to the right of the right side of the window. 

• vmin Is greater than or equal to vmax, which means that the top of the window is 
congruent with or below the bottom of the window. 

3.3.10. set^view.depth — Specify Planes for Depth Clipping 

setjoiew^depth defines the front and back planes for depth clipping. 

set_viewjdepth(frontjdistance, backjdistance) 

float frottt_distance, back_di5tance; /* Distances to Front and Back Planes */ 

Clipping to these depth bounds is controlled by eet_frontjplane_cUpping and 
4et_baehjplane_elipping. The front and back planes determine the 3-D view volume which is 
mapped to the 3-D viewport. 

SunCore initializes the front distance to 0.0 and the back distance to 1.0. 

Errors returned from setjview^depth: 

• frontjdistance is greater than back_dittance, so that the back clipping plane is in front of 
the front clipping plane. 
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3.3.11. set_viewport_2 — Establish Limits of Two-Dimensional 
Viewport 

setjineufpoTt_S establishes the limits of the viewport in two-dimensional normalised device coor¬ 
dinate space. The limits must lie in the range: 

0 < * < NDC width and 0 < y NDC height 

8et_viewport_2(xmin, xmax> ymin, ymax) 

float xmin, xmax; /♦ Left and Right sides of Viewport •/ 

float ymin, ymax; /* Bottom and Top of Viewport */ 

SunCore establishes the viewport to (0.0, 1.0, 0.0, 0.75) at initialization time. 

Errors returned from »et_v{eu>port_8: 

• xmin is greater than or equal to xmax, which means that the left side of the viewport is 
congruent with or to the right of the right side of the viewport. 

• ymtrt is greater than or equal to ymax, which means that the top of the viewport is 
congruent with or belpw the bottom of the viewport. 

• Viewport exceeds Normalized Deviced Coordinate space. 

3.3.12. set_viewport_3 — Establish Limits of Three-Dimensional 
Viewport 

9 ct_viewportjS establishes the limits of the viewport in three-dimensional normalized device 
coordinate space. The limits must lie in the range: 

0 < * < NDC width, 0 < y NDC height, and 0 < r NDC depth 

setjviewport_3(xmin, xmax, ymin, ymax, zmin, zmax) 

float xmin, xmax; /* Left and Right sides of Viewport */ 

float ymin, ymax; /* Bottom and Top of Viewport ♦/ 

float zmin, zmax; /* Front and Back of Viewport^ */ 

SunCore establishes the viewport to (0.0, 1.0, 0.0, 0.75,0.0, 1.0) at initialization time. 

Errors returned from 9et_vicu>port_Si 

• xmin is greater than or equal to xmax, which means that the left side of the viewport is 
congruent with or to the right of the right side of the viewport. 

• ymin is greater than or equal to ymax, which means that the top of the viewport is 
congruent with or below the bottom of the viewport. 

• zmin is greater than or equal to zmax, which means that the front of the viewport is 
congruent with or behind the back of the viewport. 

• Viewport exceeds Normalized Deviced Coordinate space. 
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3.3.13. set viewing parameters 

set viewing parameters specifies all the viewing parameters with a single function call. 

8et_view ing_p arameters( view_parameters) 
struct { 

float vwrefpt[3]; /* x, y, z */ 

float vwplnorm[3]; /* dx^ dy, dz */ 

float viewdis; /* View Reference Point to View Plane */ 

float frontdis; /* View Reference Point to Front Clip Plane */ 

float backdis; /* View Reference Point to Back Clip Plane */ 

int projtype; /* PARALLEL or PERSPECTIVE */ 

float projdir[3]; /* Meaning depends on projection type «/ 

float window|4]; /* umin, umax, vmin, vmax */ 

float vwupdir{3]; /* dx, dy, dz */ 

float viewport[6]; /* xmin, xmax, ymin, ymax, zmin, zmax */ 

} *view_parameters; 

The view_parameters argument is a pointer to a structure as defined above. 
set_viewin g , p arameters fills in the associated structure with the ciurrent values of the viewing 
parameters. The parameters are; 

vwrefpt 

An array of three floats describing the coordinates of the view reference point. 
vwplnorm 

An array of three floats describing the direction of the view plane normal vector. 
viewdis 

A float describing the distance of the view plane from the view reference point. 
frontdis 

A float describing the front clipping distance. 
backdis 

A float describing the back clipping distance. 
projtype 

A int describing the projection type. 
projdir 

An array of three floats describing the direction of projection. The meaning of projdir is 
dependent on the projection type: 

PARALLEL 

projdir specifies the direction of projection. 

PERSPECTIVE 

proydtV specifies the center of projection. 

window 

An array of four floats describing the boundaries of the viewing window. 
vwupdir 

An array of three floats describing the view up direction. 
viewport 

An array of six floats describing the boundaries of the viewport. 
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3.4. Viewing Control 


3.4.1. set_window_clipping — Enable Clipping in the View Plane 

sct_‘window_clipping enables or disables clipping against the window in the view plane. 

set_window_clipping(on_o£f) 

int on_off; /* TRUE = turn clipping on */ 

/* FALSE = turn clipping off */ 

The on-off argument specifies whether window clipping is enabled or not. A value of FALSE dis- 
ablct window clipping, whereas a value of TRUE enables window clipping. 

When window clipping is off, objects described to SunCore are not checked to insure that they 
lie within the window when projected onto the view plane. When window clipping is on, objects 
described to SunCore are clipped to the window. 

SunCore initializes window clipping to TRUE. 

Note that window clipping is done before segment primitives are written to the pseudo display 
file. This means that subsequent image transformations may extend images beyond the bounds 
of the viewport. SunCore has optional output clipping (an extension to the ACM Core 
specification) to correct for this. See the set_output_c!ipping function described below. 

3.4.2. 8et_front_plane_clipping — Enable Depth Clipping 

set_front_plane_,elipping enables or disables clipping against the front clipping plane. 

set_front_plane_clipping(front_on_off) 
int front_on_off; 

The front^on^off argument specifies clipping enabled or disabled for the front clipping plane. A 
value of FALSE means disable the clipping, and a value of TRUE enables the clipping. Clipping is 
disabled by default. 


3.4.3. set_back_plane_clipping — Enable Depth Clipping 

set_back_plane_clipping enables or disables clipping against the back clipping plane. 

set_back_pIane_clipping(back_on_off) 
int back_on_off; 

The baek_on_off argument specifies clipping enabled or disabled for the back clipping plane. A 
value of FALSE means disable the clipping, and a value of TRUE enables the clipping. Clipping is 
disabled by default. 
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3.4.4. 8et_putput_clipping (SunCore extension) 

SunCore supports output clipping, which is done after image transformations on segments, as 
an option in addition to window clipping. The 4 et_output_clippmg function enables or disables 
output clipping. 

8et_output_clipping(on_off) 

int on_off; /* TRUE =» turn on clipping */ 

f* FALSE ==» turn off clipping */ 

If output clipping is enabled, it places a clipping process after the image transformation specified 
by the dynamic segment attribute. This ensures that everything is correctly clipped to the 
viewport, 

3.4.5. 8et_coordinate_8ystem_type 

«€t_c 0 ordinate_sy 6 tem_type selects a left-handed or right-handed world coordinate system. 

8et_coordinate_sy8tem_type(type) 

int type; /* RIGHT = right handed coordinates */ 

/* LEFT *= left handed coordinates */ 


3.4*6. 8et_world_coordinate_inatrix_2 — Specify World or Model¬ 
ling Transform 

tetjworld_coordinatejnatriz_e specifies a 3 X 3 matrix containing the ‘world transform’ or 
modelling transform. This matrix is concatenated with the ‘viewing transform’ to give the 
‘composite viewing transform’. The composite viewing transform is the transform that is actu¬ 
ally used for all SunCore viewing transform operations. The default world coordinate matrix 
is the identity matrix. Currently, this function does not modify column 2 of the matrix. This 
function may be called at any time, even in the midst of putting output primitives into a seg¬ 
ment. 

8et_worId_coordinate_matrix_2(array) 

float array[3] (31; /* [row] [column] */ 

Note that the matrix order is such that: 

*neiC“ ** orroy[0)[0] -by* array[l][0] -h array[2][0] 
ynew =■ x * array[0}[l] + y ♦ orray[l]|l] + orray[2][l] 


3.4.7. setjworld_coordinate_matrix_3 — Specify World or Model¬ 
ling Transform 

tet_world_j:oordinate_matrix_S specifies a 4 X 4 matrix containing the ‘world transform’ or 
modelling transform. This matrix is concatenated with the ‘viewing transform’ to give the 
‘composite viewing transform’. The composite viewing transform is the transform that is actu¬ 
ally used for all SunCore viewing transform operations. The default world coordinate matrix 
is the identity matrix. Currently, this function does not modify column 3 of the matrix. This 
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function may be called at any time, even in the midst of putting output primitives into a seg¬ 
ment. 

set_world_coordinate_matrix_3(array) 

float array[4] (4]; /* [row] [column] */ 

Note that the matrix order is such that: 

xnew— t* afray[0][0] + y* «fray[l][0] + z* array[2][0] + afray[3][0] 

yneuf=^ x * arfayIoj[lj + y* array[l]H] + z * array[2][l] + array[3j[lj 

znew^ X * array[oj[2] + y * affay[l][2j + z * array(2][2j + array[Z][2\ 


3.4.8. map_ndc_to_world_2 — Convert NDC to World Coordi¬ 
nates 

mapjnde_to_world_2 maps a point in normalized device coordinate (NDC) space to its world 
coordinates. 

map_ndc_to_world_2(ndcx, ndcy, wldx, widy) 
float ndcx, ndcy; 
float ♦wldx, *wldy; 


3.4.9. niap_ndc_to_world_3 — Convert NDC to World Coordi¬ 
nates 

map_nde_to_U}orld_3 maps a point in normalized device coordinate (NDC) space to its world 
coordinates. 

map_ndc_to_worldj3(ndcx, ndcy, ndcz, wldx, wldy, wldz) 
float ndcx, ndcy, ndcz; 
float ♦wldx, ♦wldy, ♦wldz; 


3.4.10. map_world_to_ndc_2 — Convert World to NDC Coordi¬ 
nates 

map_worldjto_ndc_8 maps a point in world coordinates to its normalized device coordinates 
(NDC). 

map_world_to_ndc_2(wldx, wldy, ndcx, ndcy) 
float wldx, wldy; 
float ♦ndcx, ♦ndcy; 


3.4.11. map_world_to_ndc_3 — Convert World to NDC Coordi¬ 
nates 

map_world_to_ndcj3 maps a point in world coordinates to its normalized device coordinates 
(NDC). 
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map_world_to_ndc_3(wldx, wldy, wlds, ndcx, ndcy, ndcz) 
float wldx, wldy, wldz; 
float *ndcx, *ndcy, *ndcz; 


3.5. Inquiring Viewing Characteristics 

SunCore provides a number of functions for inquiring about parameters of the viewing opera¬ 
tions. There are a number of separate calls available for inquiring about individual parameters, 
then there is a composite inquire_viewing_parameter» function which obtains all the viewing 
parameters in one fell swoop. The individual calls provided are summarized here and described 
in detail in the subsections following. 

inguire_v{ew_jre/erenee_potnt 

Obtains the view reference point in world coordinates. 

inguire_view_pl an e_n orma( 

Obtains a vector which determines the view plane, relative to the view reference point. 
inqutre_'^evr_piane_^diatance 

Obtains the distance from the view reference point to the view plane. 
inquira_view_depth 

Obtains the distance from the view reference point to the Trout' clipping plane (also known 
as the ‘hither’ or ‘near’ clipping plane), and the distance from the view reference point to 
the ‘back’ clipping plane (also known as the ‘yon’ or ‘far’ clipping plane). 

inquire_projeetion 

Determines which projection type is in use, and returns either the center of projection (for 
PERSPECTIVE projection) or direction of projection (for PARALLEL projection). 

inquire_view_up_8 

Determines the view up direction in two dimensions. 
inquire_v{eu}jup_S 

Determines the view up direction in three dimensions. 
inquire_viewport_8 

Obtains the coordinates of the two-dimensional viewport. 
inquire_viewport_S 

Obtains the coordinates of the three-dimensional viewport. 
inquirejmndow 

Obtain the boundaries of the viewing window, 
ingtiire viewing parameters 

is a composite function which does all of the above functions at one time. 
tnqutre_n^c_spaee_8 

Determine the size of the normalized device coordinate space in two dimensions. 
tnquire_ndc_spacej3 

Determine the size of the normalized device coordinate space in three dimensions. 
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3.5.1. inquire__view_reference_point 

tnquire_vietD_referencc_point obtains the coordinates of the view reference point. 

inquire_viewjreference_point(x, y, z) 

float *x, *j, *z; /* X, y, and z Coordinates */ 


3.5.2. inquire_view_plane_nornial 

in^ire_ts'etr_p/«n«_nof»io/ obtains the coordinates of the view plane normal vector. 

inquire_jview_j)lanejiormal(dx, dy, di) 

float *dx, *dy, *d8; /* x, y, and z deltas ♦/ 


3.5.3. inquire_view_plane_diBtance 

inquire_view_plane_dittance obtains the distance of the view plane from the view reference 
point. 

inquire_view^Iane_distance{view_distance) 
float *view_distance; 


3.5.4. inquire__view_depth 

inquire_view_deptk obtains the distances of the front and back clipping planes from the view 
reference point. 

inquire_view_depth(front_distance, back_distance) 
float ^frontjdistance, ^back.distance; 


3.5.5. mquire_j>rojection 

inquire_projectton obtains the current projection type and the coordinates of the center of pro* 
jection (for PERSPECTIVE projections) or the direction of projection (for PARALLEL, projections). 

inquire_projection(projection_type, dx, dy, dz) 
int *projection_type; 

float *dx, *dy, *d8; /* x, y, and z deltas */ 


3.5.6. inquire_view_up_2 

inquire_view_up_2 obtains the view up direction in two dimensions. 

inquire_view_up_2(dx, dy) 

float *dx, *dy; /* x and y directions ♦/ 
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3.5.7. mquire_view_up_3 

m^ire_view_jupjS obtains the view up direction in three dimensions. 

inquire_view_upj3(dx, dy, dz) 

float *dx, *dy, •dz; /* x, y, and z directions ♦/ 


3.5.8. inquire_ndcjspace_2 

inqtttre^nde^spaee^B obtains the dimensions of the Normalized Device Coordinate space in two 
dimensions. 

inquire_^dcj9pace_2(width, height) 
float *width» * height; 


3.5.9. inquire_ndcjipace_3 

inquire^nde_tpaee^3 obtains the dimensions of the Normalized Device Coordinate space in three 
dimensions. 

mquire^dcjipace_3(width, height, depth) 
float *width, ^height, *depth; 


3.5.10. inquire.viewportji 

inquirejinetvport_8 obtains the coordinates of the two-dimensional viewport. 

inquirej?iewport_2(xmin, xmax, ymin, ymax) 
float *xmin, *xmax; 
float *ymin, <*ymax; 


3.5.11. inquire_vicwport_3 

in(iuire_viewporijS obtains the coordinates of the three-dimensional viewport. 

inquire_viewport_3(xmin, xmax, ymin, ymax, zmin, zmsoc) 
float *xmin, *xmax; 
float <*ymin, «ymax; 
float *zmin, *zmax; 


3*5.12. inquire_window 

in^ire.iMndsts obtains the boundaries of the viewing window. 
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inquire_window(umin, Umax, Tmin, vmax) 
float *umin, *umax; 
float «Tmin, '*Tmax; 


3.5.13« inquire_viewing_parameters 

inquirejoiewingjparamettrt returns a collection of information pertaining to the current parame¬ 
ters of the viewing system. 

ittquire_viewing_paramcters(view_parametcr8) 
struct { 

float vwrefpt[3]; f* x, y, * ♦/ 

float vwplnorm[3]; j* dx, dy, ds */ 

float viewdis; /* View Reference Point to View Plane */ 

float frontdis; /* View Reference Point to Front Clip Plane */ 

float backdis; f* View Reference Point to Back Clip Plane */ 

Int projtype; /* PARALLEL or PESISPECTIVE */ 
float projdir[3]; f* Meaning depends on projection type */ 
float window[4]; f* umin, umax, vmin, vmax *f 
float vwupdirjS]; /* dx, dy, ds */ 

float viewport[6]; /* xmin, xmax, ymin, ymax, smin, smax */ 

} *viewj)arameters; 

The vicw_parameUr9 argument is a pointer to a structure as defined above. 
inqvtircjoitwingjparameteri fills in the associated structure with the current values of the view¬ 
ing parameters. The parameters are: 

vwrefpt 

An array of three floats describing the coordinates of the view reference point. 
vtvplnorm 

An array of three floats describing the direction of the view plane normal vector. 
vievodit 

A float describing the distance of the view plane from the view reference point. 
frontdis 

A float describing the front clipping distance. 
backdis 

A float describing the back clipping distance. 
projtype 

A int describing the projection type. 
projdir 

An array of three floats describing the direction of projection. The meaning of projdir is 
dependent on the projection type: 

PARALLEL 

projdir specifies the direction of projection. 

PERSPECTIVE 

projdir specifies the center of projection. 
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tBtndow 

An array of four floats describing the boundaries of the viewing window. 
vteupdir 

An array of three floats describing the view up direction. 
viewport 

An array of six floats describing the boundaries of the viewport. 


3.5.14. inquire_jvorld_coordinate_inatrix_2 

inguire_world_eoordinate^matrix_S returns a 3 by 3 matrix containing the ‘world transform’ or 
modelling transform. This matrix is concatenated with the ‘viewing transform’ to give the 
‘composite viewing transform’. The composite viewing transform is the transform that is actu¬ 
ally used for all SunCore viewing transform operations. The default world coordinate matrix 
is the identity matrix. 

ittquirc_world_coordinatejnatrix_2(array) 
float aiTay[3][3]; /* array [row] [col] */ 


3.6.15. mquire_world_coordinate_matrix_3 

inquire^wortd_eoordinate_matrix_j9 returns a 4 by 4 matrix containing the ‘world transform’ or 
modelling transform. This matrix is concatenated with the ‘viewing transform’ to give the 
‘composite viewing transform’. The composite viewing transform is the transform that is actu¬ 
ally used for all SunCore viewing transform operations. The default world coordinate matrix 
is the identity matrix. 

inquirejworld_coordinatejnatrix_3(array) 
float array [4] [4]; /* array [row] [col] */ 


3.5.16. inquire_inverBe_compo8ite_matrlx (SunCore Extension) 

SunCore uses the matrix inverse of the composite viewing transform internally for operations 
such as rTfap^ttde_Je_wortd. This matrix may at times be useful to the applications program. 

inquire_inverse_compo8ite_m at rix (array) 
float array[4][4]; /* array [row] [col] ♦/ 


3.5.17. inquire_viewing control parameters 

inquire_viewing_eontrol_parameters obtains the enabled status of clipping, and the type of world 
coordinates in use. 
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inquire_Tiewingjcontrol_parameters(windowclip, frontclip, backclip, type) 
int *windowclip; /* TRUE if window clipping enabled */ 
int 4‘frontclip; f* TRUE if front plane clipping enabled *! 

int *backclip; f* TRUE if back plane clipping enabled */ 

int ♦type; /* RIGHT or LEFT world coordinate system type */ 


3-20 


Revision E of 7 January 1984 





Chapter 4 

Segmentation and Naming 


All output primitives for a graphical object are placed in a segment by SunCore on request 
from the application program. Each segment defines an image which is a view of the object and 
which is part of the picture displayed on the view surface. An application program describes an 
object by creating a segment, calling output primitive functions (the results of which are placed 
in the segment), and then closing the segment. 

There are two kinds of segments, namely: temporary segments and retained segments. Retained 
segments have an imagejtransformationjtype which specifies how they can be transformed. 
Retained segments can be made visible or invisible, detectable (via the pick input function) or 
undetectable, highlighted, and may be transformed, depending on their type. 

Retained segments have names (actually numeric identifiers) so that by placing output primi* 
tives in such segments, the application programmer can selectively modify parts of the picture 
by deleting and recreating segments (which effectively replaces them) so that their images 
change. Retained segments are stored in the display list for later dynamic modification. 

Temporary segments are not saved in the display list, are only drawn once, and may not be 
modified dynamically. A new_frame action deletes all portions of any temporary segments 
which have already been drawn. 


4.1. Retained S^ment Attributes 

In the same way that primitive attribut^h affect the output primitives, retained segment dynamic 
a(trt6ufe« affect the characteristics of retained segments. Prom now on, the term dynamic attri¬ 
butes means the dynamic attributes of retained segments. 

As well as being identified by the name of the retained segment into which they have been 
placed, output primitives may also be assigned a primitive attribute known as a pick identifier 
or pick-id^ This means that within the single level of segmentation, another level of naming is 
provided. An example of the use of pick-id might be that all the character strings for (say) a 
menu could appear in a single segment, where each character string is assigned a different pick- 
id. Then when the user is using the mouse to select a specific item from the menu, the applicar 
tion program uses the PICK input function to find out which menu item was selected. 

Retained segments have one static attribute and four dynamic attributes. Attributes, and the 
means of setting them and enquiring their values, are described in detail in chapter 0. 

The only static attribute of retained segments is the imagejtransformationjtype. This attribute 
can have one of five values: 
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Nont ^ u V j 

The segment is a retained segment on which no transformations may be applied. 

Tranelatable 8-D 

The segment is a retained segment which may be translated in two dimensions. 

Transformable S-D __ 

The segment is a retained segment which may be fully translated, scaled, and rotated, in 

two dimensions. 

Translatable S‘D 

The segment is a retained segment which may be translated in two or three dimensions. 
Transformable S-D 

The segment is a retained segment which may be fully translated, scaled, and rotated, in 
two or three dimensions. 

SunCore sets imagejtransformationjlype to the default value of NONE at initialization time. 
The four dynamic attributes of retained segments are defined here. 

Visibility indicates whether the segment should have a visible image. There are only two 

values of this attribute, namely: TRUE and FALSE. 

SunCore-sets the default value of visibility to TRUE at initialization time. 

Highlighting indicates whether the segment’s image should be highlighted. In SunCore, 
highlighting is done by blinking. There are only two values of the highlighting 
attribute, namely; TRUE and FALSE. When highlighting is turned on, the 
segment is blinked once. 

SunCore sets the default value of highlighting to FALSE at initialization time. 

Detectability indicates whether the retained segment can be detected by the pick device 
(mouse pointing device). Sec the await_pick function. The values for the 
detectability attribute, are: 0 through 2,147,483,647. SunCore sets the default 
value of detectability to 0 at initialization time. 


Imagejtransformation ^ 

indicates how the image of a retained segment, in normalized device coordi¬ 
nates, is scaled, rotated, or translated. A segment’s static 
imagejtransformationjtype attribute limits the values which its 
imagejtransformation attribute may have. See the set of functions called 
set_segment_image_xzx in chapter 6. 

SunCore sets the default value of imagejtransformation to the identity 
transformation at initialization time. 


4.2. Retained Segment Operations 


4.2.1. create_retained_segment — Create a New Segment 

create_retained_segment creates a new, empty, open segment. 

create_retained_segment(segment_name) 

int segment_name; /* Segment Identifier */ 
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The aegmentjaame argument defines a segment number in the range 1 through 2,147,483,647. 

The image transformation type for the newly created segment is obtained from the current 
attribute value for imagejtranaformationjttfpe. The dynamic attribute values for the newly 
created segment are obtained from the default values of the dynamic attributes for retained 8eg> 
ments. 

Use the setjimagejtrmtformationJtype function, before calling ereate_retained_segment, to 
specify whether the created segment is translatable or transformable. After calling 
create_retained_segment, the specified segment is said to be ‘‘open”. This means that output 
primitives can now be called upon to add graphics primitives (lines, text, polygons, and so on) 
to this segment. 

Only one segment can be open at a time. 

Errors returned from create_retained_jegment 

• The set of currently selected view surfaces is empty. 

• The current viewing specification is inconsistent. 

• There is already an open segment. 

• A retained segment named acgmentjname already exists. 

• The default value of imagejtrcmformation is invalid for the current 

im age^tr anafor matt onjtyp e. 

4.2.2. close.retainedjsegment — Close a Segment 

cloaejretainedjaegment closes the currently open segment. Dynamic segment attributes may be 
changed both before and after closing the segment. 

c lose_retained_8egment() 

Errors returned from clote_segment: 

• There is no open retained segment. 

4.2*3. delete.retainedjsegment — Delete a Retained Segment 

detetejretained_jegment deletes a specifically named segment. 

deletejretainedjsegment(8egment_jiame) 

lot segment^ame; /* Segment Identifier */ 

The segment specified by the tegmentjname argument is deleted. If the segment being deleted 
is the currently open segment, it is closed before it is deleted. The deleted segment is erased 
from all view surfaces. 

Errors returned from delete_retatned_eegment: 

• There is no retained segment with the name aegmentjname. 
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4.2.4* rename_retained_8egment — Rename a Retained Segment 

rcnamc_rctaintd_»cgment changes the name of a retained segment. 

rename_retained_segment(segment_name, newname) 

mt segment.nante; f* Old Segment Identifier *f 
int newname; j* New Segment Identifier *( 

The segment whose identity is »egmctit_namc is renamed as nevmame, and this name must be 
used in any future references to that segment. The segment eegmentjname is no longer accessi> 
ble. 

Errors from rename_retained_tegment. 

• There is no retained segment with the name segment^name, 

• There is an existing retained segment named neto^name. 


4.2.5. delete_all_retained_segments 

delete_aU_retained_9egmcnts deletes all retained segments. 

4plete_all_retained_8egments() 

All retained segments are deleted. If there is a currently open retained segment, it is closed 
before it is deleted. 


4*2.0. inquire.retained.segmentjsurfaces 

inquire_^retained_tegment^aur/ace9 obtains the number and names of the view surfaces upon 
which this segment gets drawn. These view surfaces were ‘selected* when the segment was 
created. 

inquire_retained_8egment_surfaces(segment_name, arrayjsize, 
vicw_purface_array, numberjofjsurfaces) 
int segment_name; /* Name of Segment */ 
int array_si*e; /* Site of View Surface Airay */ 
struct vwsurf view_8urface_array []j /* Array of view surface names •/ 

int *nttmber_of_surfaces; /* Returned number of surfaces */ 

The number of view surfaces selecteci at the time the retained segment name given by 
segment_name was created is copied into number_cf_surfaeet. The names of those surfaces are 
copied into view_»wface_arrag, where the array is an array of view surface names. erray_size is 
specified by the caller, and is the size of vieiv_surfaee_array. The view surface structure is 
defined in the use^core.h header file. 

If number_ofjturfaces is greater than arrayjsize, only array_size view surface names are copied 
into vieuf_surface_array. If erray_size is less than or equal to zero, no names are returned. 

Errors from inquire^retained_segment_surfaces: 

* There is no retained segment with the name segment_name. 
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4.2.7. inquire_retained_segment_names 

inquire^retamed_$egmentjname» obtains a list of the retained segments names. 

inquire_jretained_8egment_namcs(array_size, name_array, niimber_of_segments) 
ini array_8ize; /* Size of Array */ 

int name_array []; /* Segment Identifiers */ 

int *number_of_segments; /* Number of Segments */ 

The name_array argument is an array which is to receive a list of the existing retained seg¬ 
ments. arrayjtize specifies the number of elements in name_array. The number_of_zegmenta 
argument is returned to the caller, and is the number of existing retained segments. If the 
number of existing retained segments is greater than the size of the array, only array_<ize seg¬ 
ment names are copied into the array. If arrayjtizt is less than or equal to zero, no segment 
identifiers are returned. 

4.2.8. inquire.open_retained_8egment 

inqtiire^optnjtetainedjzegi^nt obtains the name of the currently open retained segment. 

inquire_open_jetained_8egment(segment_name) 

int *segment_name; f* Segment Name */ 

The name of the currently open retained segment (if there is one) is copied into the 
aegmentjname variable. If there is no currently open retained segment, »egment_name is set to 
zero. 


4.3. Temporary or Non-Retained Segments 

Temporary segments are used for transient images. Temporary segments cannot be modified 
dynamically, and all portions of temporary segments which have already been drawn are deleted 
upon any new frame action. Primitives placed in temporary segments are not stored in the 
display list. 


4.3.1. create.tempbraryjsegment 

crzatejtemporar^azgment creates a new, empty, nonretained or temporary, segment. 
createjtemporary_segment() 


4.3.2. close_temporary_segment 

eloae temporary aegment closes the currently open temporary segment. 
clo8e_temporaiy_segment() 
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4.3.3. mquire_open_temporaryj9egment — Get Temporary Seg¬ 
ment Status 

inquire_open_temporary^eegment determines whether there is a currently open temporary seg¬ 
ment. 

inquire_open_tem porary_segment{open) 

int «open; /* Receives status of temporary segment ♦/ 

The open argument receives the status of whether there is a currently open temporary segment: 
FALSE There is no currently open temporary segment. 

TRUE There is a currently open temporary segment. 


4.4. Saving and Restoring Segments on Disk (SunCore Extension) 

The two functions described in this section provide for saving segments on disk files and restor¬ 
ing segments from disk files. Only one segment is saved in a given file. 

4.4.1. savejsegment — Save Segment on Disk File (SunCore 
Extension) 

eave^eegment saves the named retained segment on a specified disk file. 

8ave_segment(8egment_name, filename) 

int segment^name; /* Name of segment to save */ 
char ^filename; /* Pointer to a UNIX filename */ 

Saved primitives are in normalised device coordinates. Dynamic segment attributes are also 
saved. 


4.4.2. restore^segment — Restore Segment from Disk Pile (Sun¬ 
Core Extension) 

re»tore_aegment restores the named retained segment from a specified disk file. A new segment 
is created and the segment from the disk file is copied into it. The segment is then closed. 

restore_8egment(segment_name, filename) 

int segment_name; /* Name of segment to create */ 
char * filename; /* Pointer to a UNIX filename */ 
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Output Primitives serve to describe objects in the world coordinate system. When the output 
primitive functions are called, primitives are placed in the currently open segment via dra^ving 
commands which eventually produce line and character output. 

SunCore supports six kinds of output primitives, namely moves, lines and polylines, polygons, 
text, markers and polymarkers, and rasters. 

Move , 

primitives alter the value of the Current Position (described below). 

Line 

primitives describe lines in world coordinates. 

Polj^ine 

primitives describe sequences of connected lines in world coordinates. 

Polygon 

primitives describe a closed polygon which will be filled with a color. The polygon primi¬ 
tives are a SunCore extension to the ACM Core specification. 

Text 

primitives describe character strings on the display. 

Marker 

primitives describe markers which are written on the display in a constant orientation, 
independent of any transformations which may be in effect. 

Polymarker 

primitives describe a sequence of markers which are written on the display in a constant 
orientation, independent of any transformations which may be in effect. 

Rasters 

primitive describes an array of one-bit or eight-bit pixels. 

All primitive operations use world coordinates. Some of these operations affect the value known 
as the Current Position. The Current Position defines the current drawing location in the world 
coordinate system. SunCore maintains the value of the Current Position at all times. At ini¬ 
tialisation time, the Current Position is initialized to the origin of the world coordinate system. 

In both two dimensions and three dimensions, coordinate positions can be specified in terms of 
absolute world coordinates, or coordinates can be specihed relative to the Current Position. 

A segment must be open (see the create_xxzxx_segment functions) before any output primitives 
may be used. A segment contains a set of output primitives which can subsequently be manipu¬ 
lated as a unit. 
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An output primitive is processed as follows: 

1. The primitive is transformed to clipping coordinates using the composite viewing transform. 
This places the window boundaries at umin^-SS767, umax=+32767, vmin*^-S2767, and 
vmax’^+ 32767. The front clipping plane is at and the back clipping plane is at 
z=+ 32767. 

2. The primitive is then clipped to the boundaries just mentioned if window clipping is 
enabled. 

3. The output primitive is then ovAput sealed to the viewport which is specified in normalized 
device coordinate space. 

4. The resulting primitive is then copied to the display list or pseudo display fUe (PDF) if the 
open segment is a retained segment. 

5. Next, the primitive is transformed using the image transform which is an attribute of 
retained translatable or retained transformable segments. 

6. The output primitive is then clipped again to the viewport boundaries if output clipping is 
enabled. 

7. For each view surface which was selected when the segment was created, the primitive is 
then converted to physical device coordinates and drawn on the view surface. 

If a change is made to certain dynamic segment attributes of a retained segment, the primitives 
in that segment are recovered from the PDF and used to erase the'^segment (if necessary) and 
redraw the segment following steps 5 through 7 above. The diagram below shows the above 
process in a graphical form. 

Output primitives are drawn with the static primitive attributes set by the primitive attribute 
functions (see chapter 6). 

5.1. Moving the Current Position 

There are four functions for moving the Current Position. move_abs_2 and movt^abs_3 change 
the Current Position to an absolute position in world coordinates, whereas m0ve_fdL^ and 
move_rel_3 change the Current Position by a delta relative to the Current Position. 

Note that move_abs_2 and move_Tel_2 are simply short forms of the coiresponding three- 
dimensional functions. The z coordinate of move_abs_2 is the z coordinate of the Current Posi¬ 
tion. The z delta of move_rel_2 is taken as zero. 


5.1.1. move_abB_2 — Move to Absolute 2D Position 

move__abs^2 moves the Current Position to an absolute position. 


5-2 


Revision E of 7 January 1984 






SunCore Reference Manual 


Output Primitives 



Figure 6-1; Flo'w Diagram of Output Primitive Processing 


move_abs_2(x, y) 

float X, y; /♦ x and y coordinates to move to *f 

The Current Position is set to the values of z and y in two-dimensional world coordinates. 
move_ab»_2 only sets the Current Position; no drawing commands are output. 

5.1.2. move__abs_3 — Move to Absolute 3D Position 

move^abtJS moves the Current Position to an absolute position. 
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move_abs_3(x, y, t) 

Boat X, y, z; /* x, y, and z coordinates to move to */ 

The Current Position is set to the values of z, y, and z in three-dimensional world coordinates. 
move_aba_S only sets the Current Position; no drawing commands are output. 

5.1.3. niove_rel_2 — Move to Relative 2D Position 

movc_rc/_.? increments the Current Position by the values given. 
move_rel_2(dx, dy) 

Boat dx, dy; f* x and y coordinate deltas */ 

The Current Position is set to the value of Current Position pliis dz and dy in two-dimensional 
world coordinates. move_rel_S only sets the Current Position; no drawing commands are out¬ 
put. 


5.1.4. move_rel_3 — Move to Relative 3D Position 

move_fel_S increments the Current Position by the values given. 
move_rel_3(dx, dy, dz) 

float dx, dy, dz; /* x, y, and z coordinate deltas */ 

The Current Position is set to the value of Current Position plus dx, dy, and dz in three- 
dimensional world coordinates. movejrel^S only sets the Current Position; no drawing com¬ 
mands are output. 


5.2. Position Enquiry Functions 

The position enquiry functions return the coordinates of the Current Position to the caller. 


5.2.1. inquipe„cuprent_po8ition_2 — Enquire 2D Position 

inquire_current_position_lS returns the two-dimensional world coordinates of the Current Posi¬ 
tion to the caller. 

inquire_jcurrent_j) 08 ition_ 2 (x, y) 
float *x, *y; 


5.2.2. inquire_current_po8ition_3 — Enquire 3D Position 

* • • * - ' 

inqutre_current_poaition_S returns the three-dimensional world coordinates of the Current Posi¬ 
tion to the caller. 

inquire_current_position_3(x, y, z) 
float *x, *y, *z; 
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5.3. Line Routines 

The line routines draw lines on the currently selected SunCore view surfaces. Attributes of the 
line can be specified with additional calls to primitive attribute setting routines. 

The primitive attributes of line index, linettyle, linewidth, and pick_id are applicable for lines. 
Error Codes from the Line Functions: 

• There is no open segment. 


5.3.1. line_abs_2 — Describe Line in Absolute 2D Coordinates 

line_ab$_8 describes a line in two-dimensional world coordinates. 

line_abs_2(x, y) 
float X, y; 

The line that line_ab»_8 describes extends from the Current Position to the position specified by 
the z and y coordinates. 

The Current Position is updated to the coordinates specified by x and y. 

5.3.2. line_abs_3 — Describe Line in Absolute 3D Coordinates 

Une_aba_S describes a line in three-dimensional world coordinates. 

Ime_ab8_3(x, y, z) 
float x^ y, z; 

The line that line^aba_S describes extends from the Current Position to the position specified by 
the X, y, and z coordinates. 

The Current Position is updated to the coordinates specified by x, y, and z. 

5.3.3. line_rel_2 — Describe Line in Relative 2D Coordinates 

iine_Tel_8 describes a line in two-dimensional world coordinates. 

line_rel_2(dx, dy) 
float dx, dy; 

The line that line_rel_8 describes extends from the Current Position to the position specified by 
the Current Position plus the dx and dy coordinates. 

The Current Position is updated by the deltas specified by dx and dy. 


5.3.4* line_rel_3 — Describe Line in Relative 3D Coordinates 

tine_rel_j3 describes a line in three-dimensional world coordinates. 

line_rel_3(dx, dy, dz) 
float dx, dy, dz; 

The line that line_rel_S describes extends from the Current Position to the position specified by 
the Current Position plus the dx, dy, and dz coordinates. 
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The Current Position is updated by the deltas specified by dz, <fy, and dz. 


5.4. Polyline Routines 

The polyline functions describe connected sequences of lines. The first two or three arguments 
to a polyline function are arrays of the appropriate coordinates. Consider the polyline function: 

polyline_abs_3(x_array, yjarray, z_array, n) 

float x_array [], y_array [], z_array (); /* x, y, and z coordinate arrays */ 

int n; /* Number of coordinates ♦/ 

The sequence of lines that these arrays of coordinates describe starts at the current position, 
then draws to: 

(amrrayfO], jLorroi/lO], r_orroy[0]), 
then runs through the intermediate array values and ends at 
{x_array[n~l], y„arrav[n-i\, 

where n is the number of elements in each of the coordinate arrays. There are thus n lines in 
the figure described. 

Error Codes from the Polyline Functions; 

• The number of coordinates, n, is less than or equal to zero. 

• There is no open segment. 

5.4.1. polyline_abs_2 — Describe Line Sequence in Absolute 2D 
Coordinates 

polyline_jab9_S describes a line sequence in absolute two-dimensional world coordinates. 

polyline_abs_2{x_array, y_array, n) 

float xjarray [], y_array []; /♦ x and y coordinate arrays ♦/ 

int n; /* number of array elements */ 

The Current Position is updated to the end of the last line drawn. 


5.4.2. polyline_ab8_3 — Describe Line Sequence in Absolute 3D 
Coordinates 

poljfline_abt_S describes a line sequence in absolute three-dimensional world coordinates. 

polyline_absj3(x_array, y_array, z_array, n) 

float x_array {], y_array [], z_array []; /* x, y, and z coordinate arrays *f 

int n; /* number of array elements *f 

The Current Position is updated to the end of the last line drawn. 
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5.4.3. polyUne_rel_2 — Describe Line Sequence in Relative 2D 
Coordinates 

polyline_rel_8 describes a line sequence in relative two-dimensional world coordinates. 
polyline_rel_2(dx_aiTay, dy_aiTay, n) 

float dx_array [], dy__aiTay []; /* x and y coordinate delta arrays */ 

int n; /* number of array elements */ 

The sequence of lines that this function describe starts at the current position, moves to: 

current position + (rfa:_orrfly[0), dj/Lflrray(0]) 
then draws to: 

current position + (rfa:_array[0], dj)Lflfroy[0]) 4- {dx_array[i\, rfy_arfay(l]) 
and so on. The Current Position is updated to the end of the last line drawn. 


5.4.4. poiyline_rel_3 — Describe Line Sequence in Relative 3D 
Coordinates 

polyline_rel_3 describes a line sequence in relative three-dimensional world coordinates. 

polyline_rel_3(dx_array, dy_aiTay, ds_aiTay, n) 

float dx_array [J, dy_aiTay |], dz_aiTay (]; /* x, y, and z coordinate delta arrays */ 

int n; /* number of array elements */ 

The sequence of lines that this function describe starts at the current position, moves to: 

current position -h {dx^array[0], dyjarray]^], rfr_array[0]) 
then draws to: 

current position -4* {dx_j&rray]jS\, rfj/_arroy[0], </r_array[0]) + 

(rfa!_array[l], dy_array\\\t dz_array\].\) 

and so on. The Ciurrent Position is updated to the end of the last line drawn. 

5.5. Text Routines 


5.5.1* text — Draw Character String In World Coordinates 

text draws a character string in world coordinates. 

text(string); 
char ^string; 

The character string specified by string is drawn from the Current Position. The Current Posi¬ 
tion is unchanged. The font, size, orientation, and so on, are set by calls to the set primitive 
attribute functions. 

Error Codes from the Text Function: 
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• There is no open segment. 

• The character string contains one or more characters which cannot be drawn. 

• The vectors that the current charpath and champ attributes describe are parallel. 


6.6. Text Enquiry Functions 

Text enquiry functions obtain the length that a character string would extend, in world coordi¬ 
nates, if the character string were actually drawn according to the current text primitive attri¬ 
butes. 

Error Codes from the Text Enquiry Functions: 

• inqwrc_icxt_cxtcnt_2 was used to obtain the Current Position when inq^iTt_tcxt_extcnt_S 
should have been used in order to avoid loss of information. 

• The character string contains one or more characters which cannot be drawn. 

• The vectors that the current charpath and champ attributes describe are parallel. 


5.0.1. inquire_text^extent_2 

inquirejtext_cxtent^2 obtains the two-dimensional extent, in world coordinates, of the specified 
character string. 

inquire_text_extent_2(string, dx, dy) 
char ^string; 
float *dx, *dy; 

inquire_text_extent_2 returns the extent of the character string specified by string, if the charac¬ 
ter string were drawn, unjustified, from the Current Position. The extent is returned in dx and 
dy in world coordinates relative to the Current Position. 

The specified character string, and the values of the primitive attributes font, champ, charsizc, 
charpath, charspacc, and charprccision are used to calculate the vector which represents the 
extent of the character istring. 

In the current implementation of SunCore, this function only returns meaningful values if cAor- 
prccision is CHARACTER. 


5.0.2* inquire_text_extent_3 

inquircJtext_extcnt_S obtains the three-dimensional extent, in world coordinates, of the specified 
character string. 

inquire_text_extent_3(string, dx, dy, dz) 
char ^string; 
float *dx, *dy, ♦dz; 

inquire_text_extent_S returns the extent of the character string specified by string, if the charac¬ 
ter string were drawn, unjustified, from the Current Position. The extent is returned in dx, dy, 
and dz in world coordinates relative to the Current Position. 

The specified character string, and the values of the primitive attributes font, champ, charsize, 
charpath, charspacc, and charprccision are used to calculate the vector which represents the 
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extent of the character string. 

In the current implementation of SunCore, this function only returns meaningful values if cAar 
preci.»ton is CHARACTER. 


5.7. Marker Functions 

The marker functions place a character at a specific location on the display. The polymarker 
functions place a character at a sequence of locations on the display. 

The marker character is any printable ASCII character, and is the value of the markerjtymbol 
primitive attribute. The markerjiymbol primitive attribute is set by the tetjmarker_»ymbol 
function described in chapter 0. 

The markers are placed on the display without any of the rotations, translations, or scaling 
which is applied to text strings. Markers use the default orientation attributes. 

Error Codes from the Marker Functions: 

• There is no open segment. 


5.7.1. marker_abs_2 — Plot Marker at Absolute 2D Coordinates 

marker^ab»_B plots a marker at specified absolute two-dimensional world coordinates. 
marker_abs_2{x, y) 

float x, y; f* Absolute x and y Coordinates */ 

marker_abe_B plots the marker at the absolute two-dimensional coordinates specified by the x 
and y arguments. The Current Position is updated to be this point. 


5.7.2. marker_abs_3 — Plot Marker at Absolute 3D Coordinates 

marker_ab»_3 plots a marker at specified absolute three-dimensional world coordinates. 
marker_abs_3(x, y, s) 

float X, y, z; f* Absolute x, y, and z Coordinates */ 

marker_ab$_S plots the marker at the absolute three-dimensional coordinates specified by the x, 
y, and z arguments. The Current Position is updated to be this point. 


5.7.3. marker_rel__2 — Plot Marker at Relative 2D Coordinates 

marker_rel_8 plots a marker at a specified relative two-dimensional position. 
marker_rel_2(dx, dy) 

float dx, dy; /* x and y Coordinate Deltas */ 

markerjrel^B plots the marker at the position relative to the Current Position, specified by the 
deltas dx and dy. The Current Position is updated to be this point. 
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5.7.4. inarker_rel_j3 — Plot Marker at Relative 3D Coordinates 

marktrjteljS plots a marker at a specified relative three-dimensional position. 
marker_rel_3(dx, dy, dz) 

float dx, dy, dz; /* x, y, and z Coordinate Deltas */ 

markerjrelJS plots the marker at the position relative to the Current Position, specified by the 
deltas dz, dy, and dz. The Current Position is updated to be this point. 


5.7.5. polyinarker_abs_2 — Plot Marker Sequence at Absolute 2D 
Coordinates 

polymarker^ahzJS plots a sequence of markers at specified absolute two-dimensional positions. 

polymarker_abs_2(x_array, y_array, n) 

float x_array I], y_array (]; j* Absolute x and y Coordinates ♦/ 

int n; /* Number of Coordinates */ 

polymarker_aba_8 plots a sequence of markers at the absolute positions specified by the x_array 
and y^array arguments, n specifies the number of coordinates in the arrays. The Current Posi¬ 
tion is updated to be the last point. 


5.7.6. polymarker_abB_3 — Plot Marker Sequence at Absolute 3D 
Coordinates 

polytnarker^abs_$ plots a sequence of markers at specified absolute three-dimensional positions. 

polymarker_absJ3(x_array, y_array, z_array, n) 

float x__array [], y_array{), z_aiTay (]; /* Absolute x, y, and z Coordinates */ 

int n; /* Number of Coordinates */ 

polymarker_abs_S plots a sequence of markers at the absolute positions specified by the x^array, 
y_array, and z^array arguments. The number of coordinates in the array is given by the n 
argument. The Current Position is updated to be the last point. 

5.7.7. polymarker_rel_2 — Plot Marker Sequence at Relative 2D 
Coordinates 

polymarker_rel_j8 plots a sequence of markers at specified relative two-dimensional positions. 

polymarker_rel_2(dx_aiTay, dy_aiTay, n) 

float dx_array[], dy_array []; /♦ x and Coordinate Deltas */ 

int n; /* Number of Coordinates */ 

polymarkerjrel_2 plots a sequence of markers at the positions relative to the Current Position, 
specified by the deltas dz_array and dyjxrray. The number of deltas in the arrays is specified 
by n. The Current Position is updated to be the last point. 
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5.7.8. polyinarker_rel_3 — Plot Marker Sequence at Relative 3D 
Coordinates 

polifmarker_r€l_S plots a sequence of markers at specified relative three-dimensional positions. 

poIymarker_rel_3(dx_array, dy_array, dz_array, n) 

float dx_array[), dy_array [], dz_array []; /♦ x, y, and z Coordinate Deltas */ 

int n; /* Number of Coordinates */ 

polymarkerjreljS plots a sequence of markers at the positions relative to the Current Position, 
specified by the deltas dx_array, dy_array, and dzjarray. The number of deltas in the arrays is 
specified by n. The Current Position is updated to be the last point. 


5.8. Three-Dimensional Polygon Shading Parameters (SunCore 
Extension) 

When drauring three-dimensional polygons on the Sun color displays, several shading options are 
available. The routines described in this section provide shading control. These shading param¬ 
eters may be changed at any time and are not stored in the display list. Therefore a segment 
may be drairn urith fast shading at one time, and then dra^n again later with smooth shading. 

5.8.1. set shadin g p arameters 

9et_9hadingjparametero specifies the parameters for rendering three-dimensional polygons on the 
color display. 

set_shading_parameters(ambient, diffuse, specular, flood, bump, hue, style) 
float ambient; f* percent background light */ 
float diffuse; f* percent diffuse reflection */ 
float specular; I* percent specular reflection 
float flood; f* percent flood lighting */ 
float bump; f* specular power 2 .. 9 */ 
int hue; j* color index range to generate *f 
/* 0 — 1 .. 255, 1 >=» 1 .. 63 */ 

/♦ 2 = 64 .. 127, 3 = 128 .. 191 */ 

I* A ^ 192 ., 255 */ 

Int style; /* Type of surface shading to do */ 

j* CONSTANT, GOURAUD, PHONG */ 

See 9et^olygonjinterior_9tyte for the ways in which these shading parameters are used. CON¬ 
STANT style shading gives constant intensity over the polygon using the color set by 
tet_fill^index. GOURAUD style shading linearly interpolates between vertices (use only convex 
polygons) where the intensity at each vertex is set by the aet_vertex_Jndicea function. PHONG 
style shading produces smooth shading using the other parameters (only with convex polygons). 

The shading equation with PHONG is: 

pixelshade = am6ieni' + rfi^«sc(L»N) -f spccu/or(H«N)*“*^- {flood * z) 

where L is the direction vector of the light source, N is the surface normal vector, H is a vector 
which is the average of L and E (the eye direction vector), and z is depth in NDC. 
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Here are some useful sets of PHONG parameters: 

Table 5-1: Useful PHONG Parameters 


ambient 

0.05 

0.05 

diffxue 

0.94 

0.74 

specular 

0.0 

0.20 

flood 

0.0 

0.0 

bump 

0.0 

7.0 

hue 

0 

0 

style 

PHONG 

PHONG 


5.8*2. set_light_direction — Specify Direction of Light Source 

sctJlight_direetion specifies the direction of the light source from the object. 

setJight_direction(dx, dy, dz) 
float dx, dy, dz; 

This assumes normalized device coordinate space 'where the direction from object to viewer is 
always (0.0, 0,0, -1.0). Hence, to place the light source at the viewer, the light direction is 
(0.0, 0.0, -1.0). The light direction vector is only used if the shading style is GOURAUD or 
PHONG. A useful light direction is (-0,2, 0.2, -1.0), 

5.8*3. set_vertex__norinals 

»divertez_normaU sets the surface normal vectors for each vertex of the subsequent three- 
dimensional polygon primitives {polygon_ab9_3 or potygonjrel_3). These normals are used for 
PHONG style shading. For GOURAUD style shading, use $et_vcrtez_indicea. 

8et^vertex_normals(xli8t, ylist, zlist, n) 
float xlist(], yli8t[], zlistf]; 
int n; 

The number of elements in the list, n, must be equal to the number of vertices in the subse¬ 
quent call to polygon_xzx_3. 


5.8.4. set_vertex_indices 

9et_vertcz_indicc9 specifies a color index for each vertex of the next polygon_zzx_3 primitive. 
GOURAUD shading linearly interpolates these color indices for smooth shading in the interior 
of the polygon. 
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8et^vertex_indice8(coIor_indexJist, n) 
int color_index_list []; 
int n; 

The number of elements in the list, n, must be equal to the number of vertices in the subse¬ 
quent call to polygon_xxxj3. 


5.8.5. 8et_zbuffer_cut 

ect_zbuffer_eut specifies a cutaway view of 3-D polygon objects when hidden surfaces are being 
removed. eet_zbuffcr_cut specifies an array of depths in Normalized Device Coordinate space. 
Any parts of objects which are closer to the viewer than this piecewise-linear function are 
clipped away. 

8et_zbuffer_cut(8urface_name, xlist, zlist, n) 

struct vwsurf *8urface_name; /* See appendix B */ 
float xlist[], zlist []; 
int n; 

xUtt is assumed to be monotonically increasing. This function specifies a piecewise-linear cuta¬ 
way threshold in the z coordinate, which, given any x coordinate, is constant in y. The default 
cutaway depth is 0 for all values of x. Values of x less than or greater than xlitt[n • 1] 

will have the default depth. The view surface must have been initialized with the hidden flag 
on. 


5.0. Polygon Functions (SunCore Extension) 

The polygon functions are a SunCore extension to the ACM Core specification. The polygon 
functions describe connected sequences of lines which form closed figures. The polygons are 
filled in with color as specified by the set_JUl_{ndex primitive attribute, or are shaded according 
to the current shading pt^ameters, depending on the polygonjlnterior_etyle primitive attribute. 
Only polygons created by the three-dimensional polygon functions may be shaded. 

The first two or three arguments to a polygon function are mrays of the appropriate coordi¬ 
nates. Consider the polygon function: 

polygon_ai)8_3(x_array, y_array, z_array, n) 

float x_array (], y_array (], z_array [|; f* x, y, and z coordinate arrays */ 
int n; /* Number of coordinates */ 

The bounding sequence of edges that these arrays of coordinates describe pass from the first 
point 

(z_ttrray[0], ujirray[0], z_arroy[0]), 
then runs through the intermediate array values to 
{x_array\n-l\, yLorray[n-l], z_array[n-l]), 

and then back to the first point, n is the number of elements in each of the coordinate arrays. 
There are thus n sides in the figure described. 

Note that the polygon functions describe a closed figure. The last coordinate in the array of 
points is connected to the first point. 
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Error Codes from the Polygon Functions: 

• The number of coordinates, n, is less than or equal to two. 

• There is no open segment. 

5.9.1. polygon_abs_2 — Describe Polygon in Absolute 2D Coordi¬ 
nates 

polygon_aba_8 describes a polygon in absolute two-dimensional world coordinates. 

polygon_abs_2(x_array, y_array, n) 

float x_array[), y_array(]; /* x and y coordinate arrays */ 

int n; /* num^r of array elements */ 

The Current Position is set to the first point. 

5.9*2. polygon_abs_3 — Describe Polygon in Absolute 3D Coordi¬ 
nates 

polygon_aba_S describes a polygon in absolute three-dimensional world coordinates. 

polygon_abs_3(x_array, yjwray, r_array, n) 

float x_array (], y_array[l, z_array [J; /♦ x, y, and z coordinate arrays */ 

Int n; /* number of array elements */ 

The Current Position is set to the first point. 


5.9.3. polygon_rel_2 — Describe Polygon in Relative 2D Coordi¬ 
nates 

polygon_rel_8 describes a polygon in relative two-dimensional world coordinates. The first array 
value specifies a displacement from the Current Position; remaining array values specify dis¬ 
placements from the preceding point. 

polygon_rel_2(dx_array, dy_array, n) 

float dx_array [], dy_array []; /* x and y coordinate Delta arrays */ 

int n; j* number of array elements *! 

The Ciurent Position is set to the first point. 

5.9.4. polygon_rel_3 — Describe Polygon in Relative 3D Coordi¬ 
nates 

po/ 2 /^on_re/_^ describes a polygon in relative three-dimensional world coordinates. The first 
array value specifies a displacement from the Current Position; remaining array values specify 
displacements from the preceding point. 

polygon_rel_3{dx_array, dy_array, dz_array, n) 

float dx_array {], dy_array (], dz_array []; /* x, y, and z coordinate Delta arrays 

int n; /* number of array elements */ 
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The Current Position is set to the first point. 

5.10. Raster Primitive Functions (SunCore Extension) 


5.10.1. put_raster — Raster Output Primitive 

pvtjraater dravs a rectangular 1-bit or 8-bit deep raster and enters it into the current segment. 
The raster may not be used in transformable segments, because rasters cannot be scaled or 
rotated in the current release of SunCore. A raster primitive may, however, be picked or 
dragged if it is entered in a translatable segment. The Current Position is at the lower left- 
hand corner of the raster. 

Note that put_raater is device dependent in that it is written to the right and upward from the 
Current Position a specified number of PIXELS in height and width. The Current Position is 
unchanged. 

put_raster( raster) 
struct { 

int width, height, depth; 
short '•'bits; 

} *ra3ter; 

The depth parameter can be 1 or 8 bits per pixel. 

The bits of the raster are stored in the following order for depth => 1: The first word is the upper 
left 10 horizontal bits, with the high order bit being the leftmost bit. The first {widths 15)/10 
words comprise the top row of the rectangle. The number of words of storage that bits points 
to is: 

{(width+ 16) / 10) * height 
for depth =■ 1. 

Rasters of depth » 8 are stored as successive bytes in row order. The number of bytes that bits 
points to is: 

width * height 

for depth «=« 8. 

If a 1-bit deep raster is written to a color view surface, *0’ bits select the background color and 
*1 ’ bits select the color specified by the fiU index primitive attribute. 

Note that output clipping is always done on raster primitives. 

5*10*2. get_raster — Read Raster from Black/White or Color 
Frame Buffer 

getjraster reads a specified region of the black and white or color frame buffer into a storage 
area. 


Revision E of 7 January 1984 


5-15 




Output Primitives 


SunCore Reference Manual 


get_ra8ter(8urface_name, xmin, xmax, ymin, ymax, x, y, raster) 
struct rwsurf *surface_name; /* See appendix B */ 

float xmin, ymin, xmax, ymax; /* Region of NDC space to get */ 
int X, y; /* starting point pixel offsets in raster relative top left *( 
struct { 

int width, height, depth; 
short *bits; 

} ^raster; /* Returned Raster */ 

gctjraater requires an area of memory large enough to hold the raster region that it returns. It 
is the user’s responsibility to allocate this storage area before calling getjraster. The sizejraBter 
and aliocatejraster functions may be used to do this: 

siase_raster(surface_name, xmin, xmax, ymin, ymax, &raster); 
allocatej’aster(&r aster); 
if (raster.bits ==* NULL) 

error case — the raster could not be allocated 

else 

continue with the processing 

To free the area when finished with the raster, call the freejraster function: 
freejraster(&raster); 

Hence, a large raster may be allocated and then portions of it filled with data using getjraster 
with various x, y offsets, in pixel coordinates from the top left hand comer of the raster. 


5.10.3. size_raster — Set Size of Raster in NDC 

sizejraster returns the raster with the pixel coordinates width, height, and depth, for a specified 
region of Normalited Device Coordinate space and a specified view surface. 

size_raster(surface_name, xmin, xmax, ymin, ymax, raster) 
struct vwsiuf ♦surface_name; 
float xmin, xmax, ymin, ymax; 
struct { 

int width, height, depth; 
short *bits; 

} “raster; 

On return, rasterMts is set to NULL. 


5.10.4. allocate_raster — Allocate Space for a Raster 

Given a raster whose width, height, and depth fields were filled by the sizejraster function 
(described above), allocatejraster allocates the memory required for that raster and sets the 
raster,bits pointer. 
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allocate_raster(raster) 
struct { 

int width, height, depth; 
short obits; 

} oraster; 

alloeatejraater returns a NULL pointer value in raster^bitt if it is unable to obtain enough 
memory for the raster structure. 


5.10.5* free^raster — Free Space of a Raster 

freejraster frees the memory used by a specified raster, if ra»ter,bitt is not NULL. 

free_raster(raster) 
struct { 

int width, height, depth; 
short obits; 

} oraster; 


5.10.6. raster_to_file — Copy a Raster to a Disk Raster File 

rasterjto^e copies a raster to a disk file in Sun’s standard raster file format. 

raster_to_file(raster, map, fd, replicate) 
struct { 

int width, height, depth; 
short obits; 

} Oraster; 
struct { 

int type; /* 1 for RGB color table */ 

int nbytes; /* 3 times number of color table elements */ 

ch»r odata; /* ptr to nbytes/3 red, blue, and green bytes */ 

} omap; 

int fd; /* standard UNIX file descriptor for C programs o f 

■ /o Fortran logical unit number for Fortran programs *f 
/* Pascal file variable for Pascal programs *J 
int replicate; J* magnification factor *! 

If map,nbytc$ «=> 0, no color map data will be written. This would normally be the case for ras¬ 
ters copied from the bitmap display. 

The repUcate parameter specifies whether the raster should be magnified on transmission to the 
file. The raster is transmitted without magnification if replicate — 1, and is transmitted with 
pixel-replication zoom for a factor of 2 magnification if replicate = 2. 

The format of the generated disk file can be found in the include file in 
j mrf include! ratter file,h. 
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5.10.7. file_to_raster — Get a Raster from a Disk File 

file_to_ra 3 ter allocates enough memory for a raster stored on a disk file, then fills in all fields of 
the raster and map structures. 

file_to_raster(fd, raster, map) 

int fd; /♦ standard UNIX file descriptor for C programs */ 

/* Fortran logical unit number for Fortran programs */ 

/* Pascal file variable for Pascal programs */ 

struct { 

int width, height, depth; 
short *bits; 

} *raster; 
struct { 

int type; /* 1 for RGB color table */ 

int nbytes; /* 3 times number of color table elements */ 

char *data; /♦ ptr to nbytes/S red, blue, and green bytes */ 

} '*map; 

Note that this function frees map^data, unless data is NULL, and allocates map*data each time 
it is called — therefore map,data is only valid in the last call to this function. The ratter,bits 
field is set to NULL if there is not enough room to allocate the raster. 

The format of the disk file can be found in the include file in /««r/ include/ratterJUe.h. 



t 


! 
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Chapter 6 
Attributes 


Attribute$ in SunCore specify general characteristics for segments and for output primitives. 

There are two major divisions of attributes. One set of attributes is called segment attributes 
and applies only to retained segments. The other set is called primitive attributes and applies 
only to output primitives. There are no attributes which apply to both retained segments and 
to output primitives. 

Attributes are further subdivided into static and dynamic. Static attributes specify characteris* 
tics of retained segments or output primitives which apply for the entire lifetime of those 
objects. Dynamic attributes specify characteristics of segments which can change during the 
lifetime of those segments. Static primitive attributes are stored in the display list so that sub¬ 
sequent manipulation of a segment is performed with the appropriate attributes. 




0.1. Primitive Static Attributes 

The list below defines the primitive static attribute values. 
line index 

is an index into three float arrays which determine the red, green, and blue components of 
the color displayed for line and polyline output primitives. Index value 0 corresponds to the 
background color. For lines and polylines on monochrome displays, a non-zero line index 
gives black lines on a white background. SunCore initializes line index to 1. The range of 
possible values is 0 to 255. 

fill indei 

is an index into three float arrays which determine the red, green, and blue components of 
the color displayed for polygon and raster output primitives. Index value 0 corresponds to 
the background color. For monochrome displays, the values form a set of definitions for 
texture, described later. SunCore initializes fill index to 1. The range of possible values is 
0 to 255. 

text indtx 

is an index into three float arrays which determine the red, green, and blue components of 
the color displayed for markers and text. Index value 0 corresponds to the background 
color. For text and markers on monochrome displays, a non-zero text index gives black on a 
white background. SunCore initializes text index to 1. The range of possible values is 0 to 
255. 

linestyle 

is an int value which controls the appearance of lines drawn. Linestyle can assume the 
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values: 

SOLID Solid lines, 

DOTTED Dotted lines, 

DASHED Dashed lines, 

DOTDASHED 

Dotdashed lines. 

The definitions of these constants can be found in u»trcore.h. SunCore sets linestyte to 
SOLID at initialization time. 

polygon interior ttyle 

is an int value which controls the interior filling style for polygons, polygon interior 
ttyle can have the values: 

PLAIN Solid color polygon 

SHADED Shading style is set dynamically by oet shading parameters. Only 3-D 
polygons may be shaded. 

SunCore sets polygon interior style to PLAIN at initialization time. 
polygon edge style 

is not implemented in the current release of SunCore. 

linewidth is a float value which describes, in world coordinates, the width of drawn lines. 
SunCore sets linewidth to 0.0 (the minimum) at initialization time. 

pen is an Int value which is passed to the device driver to select a particular device 

dependent pen. SunCore initializes pen to 0. 

font is an int value which determines the character font in which text will be written. 

Font can assume the following values (for c/iarprecis»on=:CHARACTER): 

ROMAN If cAarprectsiensSTRINO, this gives a raster font. 

GREEK If cAafprectsfon=STRINQ, this gives the default raster font. 

SCRIPT If cAorprectston=STRINQ, this gives a small raster font. 

OLDENGLISH If cAarprectston=>STRING, this is equivalent to ROMAN. 

STICK If cliarprect«ton=STRING, this is equivalent to GRE^. 

SYMBOLS Currently holds some electronics symbols (character values 32 through 
47). If eAarpreei«ton«nSTRING, this is equivalent to SCRIPT. 

SunCore sets font to STICK at initialization time. 

charsize is a pair of float values which determine the size of characters, in world coordinates. 

SunCore sets the default character width to 11.0 and the default character height 
to 11.0 at initialization time. 

champ attribute consists of three float values which represent a vector giving the direction 
of ‘up’ for characters: 

{dx_charup, dy_charup, dz_eharup) 

in world coordinates. Usually, champ is normal to charpath. SunCore establishes 
the default as a vector in the positive {/direction (0.0, 1.0, 0.0) at initialization time. 

charpath consists of three float values which represent a vector: 

{dx_charpath, dy_cbarpath, dz_charpath) 
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that determines the direction, in world coordinates, in which character strings will 
extend. SunCore sets the charpath attribute to (1.0, 0.0, 0.0) at initialization time. 

chartpaee is a single float value specifying the space, in world coordinates, which should be 
inserted between characters in a text string. SunCore establishes charspace with 
the value 0.0 at initialization time. 

charjutt is not implemented in the current release of SunCore. 
eharpreemon 

is an int value which controls the quality of the text drawing operation. Ckarpreci- 
»ion can have the values; 

STRING Past raster fonts, fixed size, and fixed orientation. 

CHARACTEai Hershey vector fonts. 
marker_tymbol 

determines the character which is plotted on the displays by the marker and poly¬ 
marker functions described in the chapter on Output Primitives. Any printable 
ASCII character can be used as the marker character. 

Note. The ACM Core specifies that the integer values 1 through 5 represent specific 
characters. SunCore does not implement this feature. 

pickjid is an int value identifying the next output primitive. The input primitives use this 
number for user interaction with segments and primitives within segments. 

raster op specifies the rasterop used when writing to the display. It can be one of: 

NORMAL Source value is written to the display. 

XORROP Source value is exclusive or’ed with the value already in the display 
before being written to the display. 

ORROP Source value is or’ed with the value already in the display before being 
written to the display. 

This attribute is ignored if setjirag was specified as TRUE. 

The functions listed in the subsections below each set the specified attribute value for the indi¬ 
cated primitive attribute! 

Errors returned from the primitive attribute setting functions: 

• One or more of the attribute values is incorrect. 

• No character orientation can be established because dx_ckarpath, dyjcharpath, and 
dz^eharpath are all zero. 

• No character up direction can be established because dz_charup, dy_charup, and 
dzjeharup are all zero. 

6.1.1. Using Texture for Color Attributes on the Monochrome 
Display 

When a monochrome display is used, the JUl index attribute is used to determine how a region of 
the screen is textured when using the polygon output primitives. Texturing is done in terms of 
16 X 16 pixel regions of the screen. There are 16 rows of 16 pixels each. The fill index attri¬ 
bute selects an entry from each of three arrays of float values in the range 0.0 through 1.0, 
representing red, green, and blue. In the case of the monochrome display, each of these three 
float numbers is converted to an integer between 0 and 255. Each of the 8-bit numbers is 


Revision E of 7 January 1984 


6-3 






Attributes 


SunCore Reference Manual 


divided into two four-bit quantities, which we can call A and B. _ 

o 


Table ft-1: Structure of a Fill-Index Value 


Red 

Green 

Blue 

Select 

Select 

Length 

Length 

Rotate 

Rotate 

B 

A 

B 

A 

B 

A 


Select A and Select B are four-bit values which are used to select an A pattern and a B pattern 
out of the table of numbers shown below. 
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Table 6-2: Texture Selection Values 


Four-Bit Hexadecimal 
Value Pattern 


Binary Pattern 



FFFF 


E3E3 


FFOO 


OOFF 


00000000 


100000000 


10000000 


1 0 0 0 0 1 0 0 0 


0 0 


0 0 



0 0 0 


0 0 0 


0 0 0 


1000100010001000 

1001000100100100 

1001010010010100 

1010010101010010 


1010101010101010 

1110101101101110 

1101110111011101 

1111011111110111 


1111111111111111 

1110001111100011 

1111111100000000 

0000000011111111 


The patterns are then laid down in the texture field, pixels, as descnbed m the pseudo code 
below. 
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let * = y “ Pattern A 
for index *»» 0 to Length A - \ 
pixels[index] | y 

if Rotate A & 1 then rotate z one bit right 
if Rotate A & 2 then rotate x one bit left 
if Rotate A &. A then rotate y one bit right 
if Rotate A & 8 then rotate y one bit left 

let X = y =* Pattern B 

for index = Length A to Length A + Length 5*1 
pixels[index] = x | y 

if Rotate B & 1 then rotate x one bit right 
if Rotate B & 2 then rotate x one bit left 
if Rotate B Sc A then rotate y one bit right 
if Rotate B & 8 then rotate y one bit left 

If the value of 

length A + length B 

is less than 16, the processes described above are repeated as many times as required to fill the 
16 line region. 

The above encoding provides for an enormous number of textures. Here are a few of the useful 
ones. 


Table 6*3: Useful Texture Selection Values 


Red 

Value 

Green 

Value 

Blue 

Value 

Reaultant 

Texture 

0.1334 

0.5020 

0.3529 

Hatched Left 

0.1334 

0.5020 

0.6471 

Hatched Right 

0.4667 

0.5334 

0.2118 

Wallpaper 

0.0000 

0.2667 

0.3882 

White 

0.8001 

0.2667 

0.4001 

Black 

0.1334 

0.3334 

0.4001 

Wavy Lines 

0.5334 

0.5334 

0.4001 

Grey Tone 

0.1334 

0.5334 

0.4001 

Cross Hatched 


d.1.2. define_color_indices — Assign Colors to Indices 

define^colorjindiees defines entries in the color lookup table of a view surface. 
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define_coIor_indices(8urface_iiame, il, i2, red_array, green_arra 3 r, blue_s’'Tay) 
struct vwsiuf *8urface_name; /* See appendix B */ 
int il, i2; f* indices range from 0 through 255 *f 

float red_array[], green_array[], blue_array[); 

The three aiTa 3 r 8 provide the values for red, green, and blue respectively. The value of each ele¬ 
ment in the color arrays is in the range 0.0 through 1.0. The function defines all the indices in 
the color index table between il and i2 inclusive, using the first (2- il + 1 elements from each of 
the three arrays. 

Subsequent calls to the »et_xxx_index function selects a color from the lookup table to use as a 
color attribute. 

Location 0 in the color tables is the background color for the view surface. For the mono¬ 
chrome displays, lines, text, and markers 20*6 drawn black for any color index other than 0. 

SunCore initializes the lookup table for monochrome view surfaces such that for the ith entry, 
red[i] I, green(i] = 255-*, and blue[i] =■ i. SunCore initializes color view surfaces which have 
a full 25d-element lookup table such that entry 0 is gray, entry 1 is black, entries 2 through 63 
contain an intensity ramp in red, entries 64 through 127 contain an intensity ramp in green, 
entries 128 through 191 contain an intensity ramp in blue, and entries 192 through 255 contain 
an intensity ramp in yellow (red + green). See appendix B for details of color view surfaces with 
fewer than 256 entries in the lookup table. 


6«1*3« 8et_line_iiidex — Select a Line Color Attribute 

»etjline_index selects a color by providing an index into the tables defined by the 
dcjinejcolorjindiect function. This color attribute is applied to subsequent line and polyline 
output primitives. 

setjinejndex(index) 

int index; /* range 0 through 255 */ 


6«1.4. set__filMndex — Select a Polygon and Raster Color 

tet_filUndex selects a color by providing an index into the tables defined by the 
define_€olor_indice* function. This color attribute is applied to subsequent polygon and raster 
output primitives. 

8et_fill_index(index) 

Int index; /* range 0 through 255 *f 


6.1.5. set_text_index — Select a Text and Marker Color 

9et_text^index selects a color by providing an index into the tables defined by the 
define_color_indice9 function. This color attribute is applied to subsequent text and marker 
output primitives. 
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8etjtext_index(index) 

int index; /* range 0 through 255 *f 


6.1.6. set_Unewidth 

»etjiintmdth specifies the linewidth attribute for the output primitives. 

8 et_linewidth(linewidth) 

float linewidth; /* unit of width is 1 percent of NDC space */ 

SunCore initializes linewidth to 0.0, which results in a one pixel wide line. 

If XOR'ing is enabled (via the setjraeterop or set^drag functions), lines whose pixel width is 
greater than one may partially overwrite themselves, resulting in poorly drawn wide lines. 
Redrawing the lines with XOR’ing off will draw the lines correctly (until this problem is fixed). 


6.1.7. set.linestyle 

setjlineetyle specifies the Uneetyle attribute for output primitives. 

setjine5tyle(linestyle) 

int linestyle; /* SOLID, DOTTED, */ 

/* DASHED, DOTDASHED */ 

SunCore initializes linedtyte to SOLID. 

6.1.8. set_polygon__interiop_style — Select Plain or Shaded 
Polygons 

»et^olygonjinterior_style specifies the method of filling for polygons. 

8 et_polygon_interior_8tyle(style) 

Int style; /* PLAIN, SHADED */ 

If the filling method is SHADED, polygons are shaded according to the parameters set by the 

9et_ekading_parametert function. Only 3-D polygons may be shaded. 

6.1.9. set_polygon_edgejstyle (No Effect) 

9et_polygon_edge_»tyle specifies the method of drawing the edges of a polygon. 

set_j>olygon_edge_style(style) 

int style; /* SOLID, INTERIOR *f 

This function has no effect in the current release of SunCore. 
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set^font 

eet_font specifies the font attribute for the output primitives. 

8 et_font(font) 

int font; /* ROMAN, GREEK, SCRIPT, OLDENGLISH, */ 

/* STICK, SYMBOLS */ 

SunCore initializes font to STICK. If the ckarprecieion attribute is set to STRING, ROMAN gives 
a small Roman font, GREEK gives a stick figure font, and SCRIPT gives a tiny stick figure font. 
The STRING precision fonts are ‘raster' fonts and are not scalable or rotatable, hence they are in 
pixel coordinates and are larger on the color surface than on the monochrome bitmap display. 


6.1.11. set_pen — Select a Device Dependent Pen 

This function has no effect on the standard SunCore view surfaces. 

set_pen(pen) 
int pen; 


0.1.12. set^charsize 

tttjskaroizt specifies the ekartize attribute for the text output primitive, in world coordinates. 

set_charsize(charwidth, charheight) 
float charwidth, charheight; 

If the charprecmon attribute is set to STRING, $et_ehar3ize has no effect, except to control the 
target extent of the text for the await^ick function. If the charpreeision attribute is set to 
CHARACTER, tet_ekarzize sets the average size of a character, given that each character has its 
own size. 

6.1.13. set^charspace — Define Character Spacing for Output 
Primitives 

tet^charzpace specifies the zpace attribute for the text output primitive, in world coordinates. It 
is used to insert additional space between characters in text strings. 

set_charspace(char8)>ace) 
float eharspace; 

If the charprecmon attribute is set to STRING, set_charepace has no effect. 


6.1.14. set_charup_2 

4et_^charup_B specifies the champ attribute for the text output primitive, in world coordinates. 

8 et_charup_2(dx, dy) 
float dx, dy; 
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Note that the dz offeet is set to 0.0 for this function. If the charprtcition attribute is set to 
STRING, sc(_cAorttp_;0 has no effect; otherwise it specifies the upward direction for the characters. 
This provides for slanting, mirror imaging, and so on, for characters. 


6.1.15* set_charup_3 

ztt_eharup_S specifies the charup attribute for the text output primitive, in world coordinates. 

8et_charup_3(dx, dy, dz) 
float dx, dy, dz; 

If the charprecision attribute is set to STRING, aet_charupjS has no effect; otherwise it specifies 
the direction of upward for the characters. This provides for slanting, mirror imaging and such, 
for characters. 


6.1.16. 8et_charpath_2 

set_charpath_S specifies the eharpatk attribute for the text output primitive, in world coordi¬ 
nates. 

8et_jcharpath_2(dx, dy) 
float dx, dy; 

Note that the dz offset is set to 0.0 for this function. If the eharprecmon attribute is set to 
STRING, set_charpath_B has no effect; otherwise the character string is written in this direction. 

6.1.17. set_charpath_3 

aet_charpatk_S specifies the char path attribute for the text output primitive, in world coordi¬ 
nates. 

8et_charpath_3(dx, dy, dz) 
float dx, dy, dz; 

If the charpreciaion attribute is set to STRING, act_jcharpatk_S has no effect; otherwise the char^ 
acter string is written in this direction. 


6.1.18. set__charjust — Specify Text Justification (No Effect) 

aet_charjuat specifies how text strings should be justified. 

set_charjust(just) 
int just; 

This function has no effect in the current release of SunCore. 
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6.1.10. set^charprecision 

set^charpreciaion selects the method of drawing text. 

set_charpreci8iott(charpreci8ion) 

Int charprecision; /* STRING, CHARACTER */ 

STRING Specifies chsffacters of fixed sise and orientation, which are drawn rapidly using 
raster operations. 

CHARACTER Specifies Hershey vector fonts, which can be clipped and transformed. 

6.1.20. set_marker_8ymbol 

aetjmarker^aymbol establishes the marker_aymbol primitive attribute. 
set_marker_8ymbo!(marker) 

int marker; /* Character to use as Marker — 32 .. 127 */ 

The character specified by the marker argument in the aetjmarkerjtymbol function call is subse¬ 
quently used as the marker character by the marker and polymarker functions. 


6.1.21. 8et__pick_id 

aet_pick_id specifies the pickjid attribute for output primitives. 

8 et_pickjid(pick_id) 
int pickjd; 

The piek_Jd attribute is only used by the await_pick input function. Subsequent output primi¬ 
tives are identified by the specified pickjid when they are detected by the mouse pointing dev¬ 
ice, via the atvait_piek input function. 

6.1.22. set^rasterop — Select Rasterop to Display Memory (Sun- 
Core Extension) 

aetjraaterop selects Xor’ing or or’ing of primitives to display memory. 
set_|’asterop(rop) 

int rop; /* XORROP, ORROP, normal */ 


6.1.23. Bet_j>rimitive_attpibute8 — Specify All Primitive Attri¬ 
butes 

aetjprimitivejattributea is a composite function which provides a means to set all the primitive 
attributes in a single function call. 


Revision E of 7 January 1984 


6-11 




Attributes 


SunCore Reference Manual 


8 et_primitive_attributes( attributes) 
struct { 

int lineindx, fillindx, textindx; 
int linestyl, polylinestyl, polyedgestyl; 
float linwidth; 
int pen, font; 

float cbarwidth, charheiglit; 

float charupx, charupy, charupz, charupw; 

float charpathx, charpathy, charpathz, charpathw; 

float cbarspacex, charspacey, charspacez, charspacew; 

int chjust, chquality; 

int marker, pickid, rasterop; 

} '^attributes; 

Note that the function call: 

8 et_primitive_attributes( &PR IM ATTS) 

sets all the primitive attributes to their default values. PRIM ATTS is defined in uaereore.h. 


6.2. Inquiring Primitive Static Attribute Values 

Errors returned from the primitive static attribute enquiry functions: 

• A two dimensional inquiry function was used when a three dimensional inquiry function 
should have been used to avoid loss of information. 

6.2.1. lnquire_color_indices 

inquire^color^indicea obtains the color lookup table for the specified view surface. 

inquire_colorJndices(3urface_name, il, i2, red_array, green_array, blue_aiTay) 
struct vwsurf ’»5urface_name; /* See appendix B 
int il, i2; f* Start and end table indices */ 

float red_array[); /* Range of each element is 0.0 thru 1.0 */ 
float green_jarray(]; f* Range of each element is 0.0 thru 1.0 *( 
float blue_array[J; /♦ Range of each element is 0.0 thru 1.0 */ 

awfacejnamc is the name of the view surface foh which the color lookup tables should be 

obtained. 

inquire_,color_mdices takes entries from the color lookup tables, starting at index il (relative to 

zero) and ending at index i8. The color lookup tables for a given color are stored in 

array [O] througli arroy [ i8- il ] 


6.2.2. inquire_line_mdex 

inquirejlinejlndez obtains the current color index for coloring line and polyline output primi¬ 
tives. 
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inquiTe_line_index(index) 
int *index; 


6.2.3. inquire_fill_index 

tnqutre_fill_indez obtains the current color index for coloring polygon and raster output primi* 
tives. 

inquire_fill_index(index) 
int * index; 


6.2.4. inquire_text_index 

inquirejtextjindex obtains the current color index for coloring marker and text output primi¬ 
tives. 

ittquire_text_index( index) 

Int oindex; 


6.2.5. inquire_linewidth 

inquirejlmemdth obtains the Unewidtk attribute, in percent of normalized device coordinate 
space, for the output primitives. 

inquire_Jinewidth(linewidth) 
float *Iittewidth; 


6.2.6. inquire^linestyle 

inqutre_l$ne»tyle obtains the fineatj^e attribute for the output primitives. 

inquireJine8tyle(linestyle) 

int *linestyle; /■» SOLID, DOTTED, */ 

/* DASHED, DOTDASHED */ 


6.2.7. inquire_polygon_interior_8tyle — Obtain Polygon Shading 
Method 

inquire_j>olygon^mteriorjitsdc obtains the method of filling for polygons. 

inquire_polygon_ittteriorjstyle{style) 
int *8tyle; /* PLAIN, SHADED ♦/ 
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0.2.8. inquire_polygon_edge_style 

inquirejpolygon_edgejityic obtains the current method of drawing polygon edges. 

inquire_polygon_edge_8tyle(style) 

int ♦style; /* SOLID, INTERIOR */ 


6.2.9. inquire_pen 

inquire_j>en(pen) 

int *pen; /* Device dependent pen selector */ 


6.2.10. inquire.font 

inqutre^ont obtains the font attribute for the text output primitive. 
inquire_font( font) 

Int *font; /* ROMAN, GREEK, SCRIPT, OLDENGLISH, ♦/ 
/* STICK, SYMBOLS */ 


0.2.11. inquire.charsize 

inquire_char«ize obtains the eharzize attribute for the text output primitive. 

inquire_charsizc(charwidth, charheight) 
float ♦charwidth, ♦charheight; 


6.2.12. inquire.charspace 

inguire__charspace obtains the charapace attribute for the text output primitive. 

inquire_charspace(charspace) 
float ♦charspace; 


0.2.13. inquire_charup_2 

inquire_charup__8 ohidina the charup attribute for the text output primitive. 

inquire_charup_2(dx, dy) 
float *dx, *dy; 
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6.2.14» inquire_charup_3 

inqtiire_charup^S obtains the chatup attribute for the text output primitive. 

inquire_charup_3(dx, dy, dz) 
float ♦dx, *dy, ♦dz; 


6.2.15. inquire_charpath_2 

inquire_charpath^S obtains the charpath attribute for the text output primitive. 

inquire_charpath_2(dx, dy) 
float ♦dx, ♦dy; 


6.2.16. inquire_charpath_3 

inquire^charpath_S obtains the ekarpath attribute for the text output primitive. 

inquire_charpath_3(dx, dy, dz) 
float ♦dx, ♦dy, *dz; 


6.2.17. inquire^charjuBt — Obtain Justification Attribute 

inquire_charju»t obtains the justification attribute for text strings. 

inquire_charju8t(ju8t) 
lot ♦just; 


6.2.18. inquire_ra»terop — Obtain Current Rasterop (SunCore 
Extension) 

inguirejrasterop determines the current setting of the rasterop attribute. 
inquirc_rasterop(rop) 

int ♦rop; /♦ XORROP, ORROP, NORMAL ♦/ 


6.2.19. inquire_charprecision 

$ngu$re_€harpree$sion obtains the charpreeision attribute for the text output primitive. 

inquire_charprecision(charprecision) 

int ♦charpreeision; /* STRING, CHARACTER ♦/ 
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6.2.20. inquire_pick_id 

inquire jpiekjid obtains the pick_id attribute for output primitives. 

inquire_j>ickjd(pick_id) 
int '*pick_id; 


6.2.21. inquire_niarkerjBymbol 

inqaire_markerjtymhol obtains the current value of the marker symbol. 

inquirejnarker_8ymbol(symbol) 
int *8ymbol; /♦ 32 .. 127 ♦/ 


6.2.22. inquire_primitive_attributes — Obtain All Primitive Attri¬ 
butes 

inquire_primiUve_aUrihuU* is a composite function which provides a means to obtain all the 
primitive attributes in a single function call. 

inquire_primitive_attribute8( attributes) 
struct { 

int lineindx, fillindx, textindx; 
int linestyl, polylinestyl, polyedgestyl; 
float linwidth; 
int pen, font; 

float charwidth, chuheight; 

float charupx, charupy, champs, champw; 

float charpathx, charpathy, charpaths, charpathw; 

float charspacex, charspacey, charspacez, charspacew; 

int chjust, chquality; 

int marker, pickid, rasterop; 

} ^attributes; 


6.3. Retained Segment Static Attributes 

There is only one static attribute for segments. This is the image_tran»formaiion_t]/pt attri¬ 
bute. This attribute can take on one of five values: 

NONE Retained segment on which no translation, scaling, or rotation can be performed. 

XLATE2 Translatable retained segment. The segment can be moved (translated) in two 
dimensions (x and y of NDC space). 

XFORM2 Fully transformable retained segment. The segment can be moved (translated), 
rotated, and scaled (have its size changed) in two dimensions (x and y of NDC 
space). 

XLATE3 Translatable retained segment. The segment can be moved (translated) in three 
dimensions (x, y and z of NDC space). 
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XFORM3 Fully transformable retained segment. The segment can be moved (translated), 
rotated, and scaled (have its size changed) in three dimensions (x, y and z of NDC 
space). 

The imagejtramformationjtype attribute is set when a segment is created and cannot be 
changed at any time during the life of the segment. The default value of 
mageJtraMformatioftJtype is NONE. 

The functions described below are used to set and enquire about the values of 
imageJtransformationJtype. 

6*3.1. set_image_transformation_type 

aet_JmageJtransformation_Jype specifies the imagejtramformationjtype attribute for subse¬ 
quently created segments. 

set_imagejtransformation_type(type) 

int type; /* NONE, XLATE2, XFORM2, XLATE3, XFORM3 */ 

6.3.2. mquire_image_transformation_type 

inqairejimagejramformatibnjype obtains the current value of the imagejramformationjype 
attribute. 

inquire_image_transformation_type(type) 

int *type; /* NONE, XLATE2, XFORM2, XLATE3, XFORM3 */ 


6.3.3. inquire_segment_image_J}ransformation_type 

inquire_aegment_imageJramformation_type obtains the imagejramformationjype for a 
specified segment. 

inquire_segment_image_transformation_type(segment_name, type) 
int segment^name; /* Name of segment for inquiry */ 
int Hype; /♦ NONE, XLATE2, XFORM2, XLATE3, XFORM3 */ 

1 

6.4. Setting Retained Segment Dynamic Attributes 

In addition to the one static attribute described above, there are a number of dynamic attri¬ 
butes which apply to segments. Each retained segment has its own set of dynamic attributes, 
as listed below. 

Viaibility indicates whether the segment should have a visible image. There are only two 
values of this attribute, namely: TRUE and FALSE. 

SunCore sets viaibility to TRUE at initialization time. 

Highlighting indicates whether the segment’s image should be highlighted. In SunCore, 
highlighting is done by briefly blinking the segment. There are only two values of 
the highlighting attribute, namely, TRUE and FALSE. 


Revision E of 7 January 1984 


6-17 





Attributes 


SunCore Reference Manual 


SunCore sets highlighted to FALSE at initialization time. 

Detectability indicates ■whether the retained segment can be detected by the await^ick input 
primitive. A value of 0 means that the segment is not pickable. If two segments 
overlap, the one with the greatest value of detectability is the one that gets picked. 
SunCore sets detectability to the default value of 0 at initialization time. 

Imagejtramformation 

indicates how the image of a retained segment is scaled, rotated, or translated. 
Image transformations are done in NDC space, ie. after all viewing operations have 
been performed. Image transformations do not compose and do not cumulate. 
Whenever any function affecting a segment’s image transformation is called, the 
transformation is reset to reflect only the values specified by the call. The 
imagejlramformation attribute of a segment must be consistent with its 
imagejtraneformationjtype attribute (for instance, if the 
imagejtraneformationjtype is XLATE2, it is an error to attempt to rotate the seg¬ 
ment). 

SunCore sets the default imageJtransformation to the identity transformation 
(that is, no translation, scaling, or rotation) at initialization. 

There are two classes of functions for setting retained segment dynamic attributes. One class 
sets the default attributes for subsequently created segments; the other sets attributes on a 
named segment basis. 

Errors which can be returned from the retained segment dynamic attribute setting routines are: 

• There is no retained segment called segmentjname, 

• One or more of the attributes is incorrect. 

• The segment’s imagejtransformationjtype attribute value is incompatible with the 
requested function. 

6.4.1. set^visibility 

»et_vieibility specifies the default vi>i6t7i(y attribute for subsequently created segments. This 
does not affect the visibility of existing segments or the currently open segment. 

set_visibility(visibility) 

int visibility; /* TRUE or FALSE */ 

6.4.2. set^highlighting 

eet_highlighting specifies the default highlighting attribute for subsequently created segments. 

3 et_highlighting( highlighting) 

int highlighting; /♦ TRUE or FALSE */ 


6.4.3. set_detectability 

»€t_detectability specifies the default detectability attribute for subsequently created segments. 
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8 et_detectability( detectability) 

Int detectability; /* 0 thru 2^-1 */ 


6.4.4* 8et_image_tpanslate_2 

tet_imagejtranalate_8 sets the default image traiwformation attribute for subsequently created 
segments. 

set_imagejtranslate_2(tx, ty) 

float tx, ty; /♦ x and y translation values in NDC */ 

The default image transformation is set to a tvro-dimensional translate by tx and ty. 


6.4.5. setJimage_tran8formation_2 

aet_image_tranaformation_S sets the default image transformation for subsequently created seg¬ 
ments. 

8et_image_transformation_2(sx, sy, a, tx, ty) 
float sx, sy; /* x and y Scale Factors */ 

float a; /* Rotation Value in radians clockwise about the z axis */ 

float tx, ty; /* x and y Translation Values in normalized device coordinates */ 

The default transformation is set to a two-dimensional scale by ax and ay, rotation by a, and 
translation by tx and ty. The order of transformation is: 

1. Spate about the origin of NDC space. 

2. Rotate about the origin of NDC space (about the z axis). A positive rotation of it/2 
radians will rotate the x axis into the y axis. 

3. Tranalate. 

To scale and rotate about a point x, y, add dx to tx and add dy to ty, where 

dx = X - (x * sx * co4(a) - y * sy ♦ «m(a)) 
dx = y - (x * sx ♦ «in(a) + y * sy * CM(a)) 


6.4.6. 8et_image_translate__3 

aet_,image_tranBtate_3 sets the default image transformation attribute, in normalized device 
coordinates, for subsequently created segments. 

8etjmage_translate_3(tx, ty, tz) 

float tx, ty, tz; /* x, y, and z Translation Values in NDC */ 

Tile default image transformation is set to a three-dimensional translate by tx, ty, and tz. 
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6.4.7. set_image_tran8formationj3 

tet_tmageJtransformatiott^3 sets the default image transformation attribute for subsequently 
created segments. 

setJmagejtran3formation_3(sx, sy, ss, ax, ay, az, tx, ty, tz) 
float sx, sy, sz; /* x, y, and z Scale Factors */ 
float ax, ay, az; }* Rotation Values in radians clockwise */ 

I* about the x, y, and % axes. <*/ 
float tx, ty, tz; /* x, y, and z Translation Values in NDC */ 

The default image transformation is set to a three-dimensional scale by mx, ay, az, a three- 
dimensional rotation by ax, ay, az, and a three-dimensional translation by tx, ty, tz. The order 
of transformation is: 

1. Seale about (0.0, 0.0, 0.0) in NDC space, 

2. Rotate about (0.0, 0.0, 0.0) in NDC space, first about the >axis, then about the j^axis, and 
then about the >axis. Since NDC space is a left-handed coordinate system, rotations are 
computed using the left-hand rule. When the origin is viewed from the positive side of the 
axis of rotation, clockwise rotations correspond to positive rotations. 

3. Tranalate. 


6.4.8. 8etjsegment_visibility 

aetjaegmenijuiaibility specifies the viatbiUty attribute for the named segment. 

set_segment_visibility(segment_name, visibility) 

Int segment.name; 

int visibility; /* TRUE or FALSE */ 

When viaibtlity is set to FALSE, the segment is erased from the view surfaces. The segment is 
redrawn again when viaibility is set to TRUE. 

6.4.9. 8et_segment_highlighting 

aet_aegmentjbigktightmg specifies the kightighting attribute for the named segment. 

set_segment_highlighting(segment_name, highlighting) 
ini segment^name; 

int highlighting; /* TRUE or FALSE */ 

When highlighting is set to TRUE, the segment is blinked once. 


6.4.10. set_segment_detectability 

aet_aegment_deteetability specifies the detectability attribute for the named segment. 

set_segment_detectability(segment_name, detectability) 
int segment_name; 

int detectability; /* 0 thru 2^-1 */ 
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When detectability is set to 0, the segment cannot be picked by the await_pick input function. If 
two segments overlap, the segment with the greatest detectability is picked. 


6.4.11. set_segment_image_translate_2 

cet_eefffnettt^imaye_tranelate_S sets the image transformation attribute for the named segment. 

8et_8egment_image_tran3late_2(segment_name, tx, ty) 
int segment_name; 

float tx; /* X Translation Value in NDC */ 
float ty; /* y Translation Value in NDC */ 

The image transformation is set to a two-dimensional translate by tz, ty. The named segment is 
erased from the view surface and then redrawn after the new image transformation is applied. 
This may be done while the segment is open. 


6.4.12. set_8egment_image_transformation_2 


set^eegment_image^tran»/ormation^B sets the image transformation attribute for the named seg¬ 
ment. 


set_8egmentjmage_tran5formation_2(segmcnt_name, sx, sy, a, tx, ty) 
int segment.name; 
float sx; /* X Scale Factor */ 

float sy; /* y Scale Factor */ 

float a; /* Rotation Value in radians clockwise about the z axis*/ 
float tx; /* X Translation Value in NDC ♦/ 

float ty; /* y Translation Value in NDC */ 


The image transformation is set to a two-dimensional scale by sz and sy, a two-dimensional 
rotation by a, and a two-dimensional translation by tz and ty. The order of transformation is: 

1. 5ca/e about the origin of NDC space. 

2. Botate about the origin of NDC space (about the z axis). A positive rotation of tr/2 radians 
will rotate the x axis into the y socis. 

3. Translate. 

To scale and rotate aljout a point x, y, add dx to tx and add dy to ty, where 

dx X - (x * sA * cos(a) - y * sy * «n(a)) 
dx = y - (x * sx ♦ sin(a) + y * sy * cos(a)) 


The named segment is erased from the view surface and then redrawn after the new image 
transformation is applied. This may be done while the segment is open. 


6.4.13. set_segment_image_translate_3 

set_segment_image_transtate_S sets the image transformation attribute for the named segment. 
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set_segment_image_tran3late_3(segment_name, tx, ty, tz) 
int 8egmeiit_name; 

float tx; j* X Translation Value in NDC */ 

float ty; /* y Translation Value in NDC */ 

float tz; /* z Translation Value in NDC */ 

The image transformation is set to a three-dimensional translate by tx, ty, tz. The named seg¬ 
ment is erased from the view surface and then redrawn after the new image transformation is 
applied. This may be done while the segment is open. 


6.4.14. set_segment_image_transformation_3 


tet_aegmcnt_itnage_ttcinBformation_3 sets the image transformation attribute for the named seg¬ 
ment. 


set_segment_imagejtransformation_3(segment_namc, sx, sy, sz, ax, ay, az, tx, ty, tz) 
Int segment_name; 
float sx; /* X Scale Factor ♦/ 

/* y Scale Factor */ 

/♦ z Scale Factor */ 

/* Rotation Value in radians clockwise about the x axis */ 

/* Rotation Value in radians clockwise about the y axis */ 

/* Rotation Value in radians clockwise about the z axis */ 

/* X Translation Value in NDC */ 

/• y Translation Value in NDC */ 

/♦ z Translation Value in NDC */ 


float sy; 
float sz; 
float ax; 
float 
float 
float 


ay; 

tx; 


float ty; 


float tz; 


The image transformation Is set to a three-dimensional scale by sx, sy, sz, a three-dimensional 
rotation by ax, ay, az, and a three-dimensional translation by tx, ty, tz. The order of transfor¬ 
mation is: 

1. Scale about (0.0, 0.0, 0.0) in NDC space. 

2. Rotate about (0.0, 0.0, 0.0) in NDC space, first about the »-axis, then about the j^axis, and 
then about the r-axis. Since NDC space is a left-handed coordinate system, rotations are 
computed using the left-hand rule. When the origin is viewed from the positive side of the 
axis of rotation, clockwise rotations correspond to positive rotations. 

3. Translate. 

The named segment is erased from the view surface and then redrawn after the new image 
transformation is applied. This may be done while the segment is open. 


6.5, Inquiring Retained Segment Dynamic Attributes 

The functions described below are for inquiring the settings of the dynamic attributes for 
retained segments. There are two classes of functions for inquiring retained segment dynamic 
attributes. One class obtains the default attributes for subsequently created segments and the 
other obtains attributes on a named segment basis. 

Errors which can be returned from these functions are: 
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• There is no segment called »egtnent_namc. 

• The default image transformation attribute value is of a more complex type than the 
inquiry function used. 

• The segment’s imageJiran»formation_typc attribute value is incompatible with the 
requested function. 

• The segment’s imagejtrantformationjtype attribute value is of a mOTe complex type than 
t|(e inquiry function used. 

0.5.1. inquire_visibility 

in9uire_vtsibt7ity obtains the default vitibiUty attribute for subsequently created segments. 

inquire_visibility(visibility) 

int *vi5ibility; /* TRUE or FALSE */ 

0.5.2. inquire_highlighting 

inquire_highlighting obtains the default highlighting attribute for the subsequently created seg¬ 
ments. 

inquire_highlighting( highlighting) 

int * highlighting; /* TRUE or FALSE */ 

0.5.3. inquire.detectability 

inquire^deteetability obtains the default detectability attribute for the subsequently created seg¬ 
ments. 

inquire_detectability(detectability) 

int ^detectability; /♦ 0 thru 2”-l */ 


0.5.4. inquire_image_translate_2 

inguire_imagejtranslate_8 obtains the two-dimensional translation components of the default 
image transformation for subsequently created segments. 

inquirejlmagejbran5late_2(tx, ty) 

Boat *tx, ♦ty; /♦ x and y Translation Values in NDC */ 


0.5.5. mquire_image_transformation_2 

inquire_image_tran8formation_8 obtains the two-dimensional scale factor, rotation, and transla¬ 
tion components of the default image transformation attribute for subsequently created seg¬ 
ments. 
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inquire_imagejtransformation_2(sx, sy, a, tx, ty) 
float *sx, ♦sy; /■•‘ x and y Scale Factors */ 

float *a; f* Rotation Value in radians clockwise about the z axis*/ 
float ♦tx, *ty; /* x and y Translation Values in NDC */ 


6.5*0. inquire_image_tran8late_3 

inqaircJimaQeJtrantlatejS the three*dimen8ional translation components of the default 

image transformation attribute for subsequently created segments. 

inquire_imagejtran5latej3(tx, ty, tz) 

float '♦tx, ♦ty, *tz; /* x, y, and z Translation Values in NDC */ 


6.5.7. inquire_image_tran8formation_3 

inquireJitnagt_tTan»foTmation_3 obtains the three-dimensional scale factor, rotation, and trans¬ 
lation components of the default image transformation attribute for subsequently created seg¬ 
ments. 

inquire_image_transformation_3(8X, sy, sz, ax, ay, az, tx, ty, tz) 
float *8X, *sy, *sz; /* x, y, and t Scale Factors */ 
float ♦ax, ♦ay, ♦az; /♦ Rotation Values in radians clockwise about the ♦/ 

/* x, y, and z axes */ 

float *tx, *ty, ♦tz; /♦ x, y, and z Translation Values in NDC ♦/ 


6.5.8. inquirejsegment_visibility 

inquire_»egmtntji)i»ihility obtains the vi$ibilitg attribute for the named segment. 

inquire_segment_visibiHty(segment_name, visibility) 
int 8egment_name; 

int ♦visibility; /♦ TRUE or FALSE •/ 

6.5.9. inquire_8egment_highlighting 

inquire_»egmentjfiighlighiing obtains the highlighting attribute for the named segment. 

inquire_8egmentjhighlighting(8egment_name, kighlighting) 
int segment_name; 

int * highlighting; /* TRUE or FALSE ♦/ 

6.5.10. inquirejsegment_detectability 

inquire_scgmcnt_detcctabilitychtsAns the (/cfccfaftt/ify attribute for the named segment. 
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inquire^8egment_jdetectability(3egment_name, detectability) 
int segment_name; 

int ♦detectability; /* 0 thru 2”“1 */ 


6*5.11. inquirejsegmenOiiiage_translate_2 

inqutre_4egTnMt_{mage_tran9tate_S ot>tains the two-dimensional translation components of the 
named segment’s image transformation attribute. 

inquirejiegment_image_translate_2(segment_name, tx, ty) 
int 8egment_name; 

float *tx; /* X Translation Value in NDC */ 
float ♦ty; /♦ y Translation Value in NDC */ 


6.5.12. inquire_segment_image_transformation_2 

inquiTe^9egment_{m<ige_trattsformation_8 obtains the two-dimensional scale factor, rotation, and 
translation components of the named segment’s image transformation attribute. 

inquire_pegmetttJmagejtransformation_2(segment_name, sx, sy, a, tx, ty) 
int segment^name; 
float *8x; /♦ X Scale Factor ♦/ 

float ♦sy; /♦ y Scale Factor */ 

float ♦a; /♦ Rotation Value in radians clockwise about the z axis*/ 

float ♦tx; /♦ X Translation Value in NDC */ 

float ♦ty; /♦ y Translation Value in NDC */ 


6.5.13. inquire_segment_iniage__tran8late_3 

inquire_tegmentjimage_tran$iate_S obtains the three-dimensional translation components of the 
named segment’s image transformation attribute. 

inquire_8egment_image_translate_3(8egment_name, tx, ty, tz) 
int segment_;iame; 

float ♦tx; /♦ X Translation Value in NDC ♦/ 

float ♦ty; /♦ y Translation Value in NDC */ 

float ♦tz; /♦ z Translation Value in NDC ♦/ 

6.5.14. inquirejsegment_image_transformation_3 

inquire_9egmcnt_image_Jraniformation_S obtains the three-dimensional scale factor, rotation, 
and translation components of the named segment’s image transformation attribute. 
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jnquire_segment. 

int segment, 
float '•^sx; 
float *sy; 
float *sz; 
float *ax; 
float *ay; 
float ’*az; 
float *tx; 
float *ty; 
float Hz; 


jmagejtransformation..3(8egment_name, sx, sy, sz, 
ax, ay, az, tx, ty, tz) 

.name; 

/* X Scale Factor */ 

/* y Scale Factor ♦/ 

/* z Scale Factor */ 

/* Rotation Value in radians clockwise about the x axis */ 
/* Rotation Value in radians clockwise about the y axis */ 
/* Rotation Value in radians clockwise about the z axis */ 
/* X Translation Value in NDC */ 

/* y Translation Value in NDC ♦ / 

I* z Translation Value in NDC */ 
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SunCore supports several logical input devieea providing for interactive use of the graphics sys¬ 
tem. The physical input devices provided are the keyboard and the mouse. The mouse is veiv 
satile in that it can be used both as a pointer and a button device. 

In the terminology of the ACM Core specification, input devices fall into two distinct classes, 
namely: devices that generate events, and devices that may only be sampled for position or 
numerical values. SunCore supports the ACM Core standard level 2 input (synchronous); 
hence no event generation or event queue is supported. The supported logical devices in Sun¬ 
Core are: 

Pick 

identifies (picks out) a segment or a primitive within a segment. SunCore uses the mouse 
as a pick device. 

Keyboard 

provides alphanumeric information to the application program. 

Button 

provides a means of choosing among several alternatives. In SunCore, the three button 
devices are on the mouse. 

Stroke 

generates a sequence of positions in normalized device coordinates. In SunCore, the stroke 
device is the mouse. 

Locator 

provides a position in normalized device coordinates. SunCore uses the mouse as the locar 
tor device. 

Valuator 

provides a scalar value to the application program which samples it. SunCore uses the 
mouse as the valuator device. 

A logical input device must be initialized before it can be used. 


7*1. Initializing and Terminating Input Devices 
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7.1.1* initialize_device — Initialize a Specific Device 

initiaiize^device initializes a specific logical device. This routine must be called before accessing 
any of the input devices. 

initia!ize_device(device_class, device_number) 

int device.class; /* PICK, KEYBOARD, STROKE */ 

/♦ LOCATOR, VALUATOR, BUTTON */ 

int device_number; /* There are: */ 

/* 1 PICK device */ 

/* 1 KEYBOARD device */ 

/* 1 STROKE device */ 

/* 3 BUTTON devices */ 

/♦ 1 LOCATOR device */ 

/* 1 VALUATOR device */ 

An initialized input device which uses position information from the mouse must be associated 
with an initialized view surface (as an echo surface) before valid data can be read from the dev> 
ice. See appendix B for details. 

Errors returned from initiatize_device: 

• The device specified by devicejnumber is not initialized. 

• The device specified by devicejnumber is already initialized. 

Note: that if the KEYBOARD device is initialized and the program crashes before the 
KEYBOARD device is terminated, the tty will not echo and ebreak will be set. To 
recover from this condition, type ‘reset’ followed by a carriage return. 

7.1.2. terminate^device — Disable a Specific Device 

terminate_deviee disables a specific device. 

terminate_device(device_clas8, device_number) 

int device^class; /* PICK, KEYBOARD, STROKE */ 

/* LOCATOR, VALUATOR, BUTTON */ 


int device_number; 

h 

There are: */ 


h 

1 PICK device */ 


h 

1 KEYBOARD device */ 


1* 

1 STROKE device */ 


/* 

3 BUTTON devices */ 


h 

1 LOCATOR device */ 


1* 

1 VALUATOR device */ 

Errors returned from terminate_d€vtce: 



• The device specified by device_number is not enabled. 


7-2 


Revision E of 7 January 1984 



SunCore Reference Manual 


Input Primitives 




7.2. Device Echoing 

Device echoing means that SunCore can provide a visible indication to the user that the sys¬ 
tem has seen the input from a specific input device. 

SunCore provides the means whereby the application programmer can control the way in 
which input devices are echoed to the user of the graphics s 3 rstem. 

Firstly, the types of echoing for each device are defined here. The tables below describe the 
types of echoing for specific devices. 

Table 7-1; Echoing for Pick Device 



Pick Device 

Echo Type 

Actions Performed 

0 

No echo 

1 

SunCore blinks the picked segment briefly. A printer’s fist (pointing finger) 
indicates the position of the pick device. 

2 

A printer’s fist (pointing finger) indicates the position of the pick device. Sun¬ 
Core does not blink the picked segment. 


Table 7-2; Echoing for Keyboard Device 



Keyboard Device 

Echo Type 

Actions Performed 

0 

No echo 

1 

Tke string which the user typed at the keyboard is echoed on the screen start¬ 
ing at the echo reference position. 


t 
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Table 7-3: Echoing for Button Device 



Button Device 

Echo Type 

Actions Performed 

0 

No echo 

1 

No echo 

Table 7-4: Echoing for Stroke Device 


Stroke Device 

Echo Type 

Actions Performed 

0 

No echo 

1 

a printers fist (pointing finger) sign is displayed at the cursor position. 

2 

A string of dots is dravrn to follow the path of the cursor, (not implemented) ^ 

C 

3 

A solid line is drawn to follow the path of the cursor, (not implemented) 

4 

a printers fist sign is displayed at the final position of the cursor, (not imple¬ 
mented) 


o 
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Table 7-5: Echoing for Locator Device 


Echo Type 

Locator Device 

Actions Performed 

0 

No echo 

1 

A printers fist (pointing finger) sign is displayed at the position of the locator. 

2 

A solid line is drawn connecting the echo reference point with the locator. 

3 

A solid line is drawn connecting the echo reference point with the x coordinate 
of the locator. 

4 

A solid line is drawn connecting the echo reference point with the y coordinate 
of the locator. 

5 

A solid line is drawn connecting the echo reference point with either the x coor¬ 
dinate, or the y coordinate, of the locator, whichever is farthest from the echo 
reference point. 

6 

A box is drawn with the position of the locator as one corner, and the echo 
reference point as the opposite corner. 


Table 7-6: Echoing for Valuator Device 



Valuator Device 

Echo Type 

Actions Performed 

0 

No echo 

1 

The current value of the valuator is displayed on the screen starting at the 
echo reference point. 

2-11 

SunCore does not perform the actions as described in the ACM Core 
specification, which sets the values of the valuator into various parameters of 
the image_tramformationJtype attribute of retained segments. SunCore 
leaves this up to the application program. 
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7.2.1. Bet_echo — Define Type of Echo for Device 

set eclio(device_class, device_number, echo_type) 

Tnt device.class; /* PICK, KEYBOARD, STROKE, */ 

/♦ LOCATOR, VALUATOR, BUTTON */ 

int device_number; 
int echo_type; 


7.2.2. setjecho_group — Define Type of Echo for a Group of Dev¬ 
ices 

8et_echo_group(device_class, device_number_array, n, echo_type) 
int device^class; /* PICK, KEYBOARD, STROKE, */ 

/* LOCATOR, VALUATOR, BUTTON */ 
int device_number_anray[]; 
int n; /* number of devices in array ♦/ 

int echo_type; 


7.2.3. 8etjecho_position — Define Echo Reference Point 

8 et_ccho_position specifies the position, in normalized device coordinates, which will be used as 
the echo reference point. The coordinates must lie within the bounds of NDC space, or 
8et_echo_position will set the echo reference point to be the point in NDC space closest to the 
specified point. 

set_echo_position(device_cla3S, device_number, echo^, echo_y) 
int device_class; /* PICK, KEYBOARD, STROKE, */ 

/* LOCATOR, VALUATOR, BUTTON */ 

int device_number; 

float echo_?c; /* x Coordinate of Echo Point */ 

float echo_y; /* y Coordinate of Echo Point */ 

The echo reference point that this function defines is used for certain types of echo such as 
rubber band locator echo. 

7.2.4. set_echo_surface — Define View Surface for Echo 

set_echo_j8urfatie specifies the viewing surface on which echoing will be done. 

set_echo_surface(de'vice_class, device_number, surfacejaame) 
int device.class; /♦ PICK, KEYBOARD, STROKE, */ 

/* LOCATOR, VALUATOR, BUTTON */ 

int device_number; 

struct vwsurf *surface_name; /♦ See appendix B ♦/ 

An initialized input device which uses position information from the mouse must be associated 
with an initialized view surface (as an echo surface) before valid data can be read from the 
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device. See appendix B for detmls. If a NULL pointer is pven for the surfacejname argument, 
any association of the specified input device with an echo surface is ended. 


7.3. Setting Input Device Parameters 


7.3.1. setJocatorJ2 — Initialize Locator Position 

setJloeatprJB sets the initial locator position in normalised device coordinates. 

setjocator_2(locator_number, x, y) 
int Iocator_jmmber; 
float x; 
float y; 

SunCore currently does not use this initial position of the locator. 


7.3.2. Bet_valuator — Initialize Value and Range for Valuator 
Device 

setjoaluator sets the value and range for the valuator device. 

8etjvaluator(valuator_numbcr, initialjralue, low, high) 
int valttator_vumber; 
float initialjvalue; 
float low; 
float high; 

The default values are; initialjifaluc «» 0.(7, low 0.0, and htgk — 1.0. 

7.3.3. set^keyboard — Initialize Keyboard Parameters 

oetjsejfioard sets the size of the character buffer for the keyboard, the initial character string, 
and the initial character cursor counting from the echo reference position. 

8ctJceyboard(keyboaTd_uumber, bufferjsize, initialjitring, initial_cursor_position) 
int keyboardjiumber; 
int bujEferjiize; 
char ^initialjitring; 
int initialjeur 8 or_p 08 ition; 

SunCore uses default values of bufferjtize =» 80, ini(rinjy = "enter:”, and 
irutidjeuroor .position»7. The maximum bufferjsize and the maximum length of 
initialjitring are 80 characters. 
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7.3.4. setjstroke — Initialize Stroke Device 

t€t_ttroke sets parameters for the stroke device. 

set_stroke(8troke_number, buffer_si 2 e, distance, time) 
int stroke_number; /* Device Number */ 

int buffer_size; /* Number of x, y points - not used ♦/ 

float distance; /* Minimum distance to move */ 

int time; /* Not used */ 

The buffer_sizc argument is the maximum number of x, y points in a stroke. The distance argu* 
ment is the minimum distance, in normalized device coordinates, which the mouse must move 
before a new point is added to the x, y list comprising the stroke. The default setting is dis- 
fance’=0.01. 


7.4. Reading From Input Devices 


7.4.1. await_any_button — Wait for Mouse Button 

aipatt any button waits for the user to click any of the mouse buttons. 

await_any_b*itton(time, buttonjiumber) 

int time; /* Time in microseconds to wait */ 
int * buttonjiumber; /* Button which was hit */ 

await any button waits for the user to click any initialized button on the mouse, or until the 
time specified by the time parameter expires. If the time argument is exactly zero, the buttons 
are checked once, then the function returns to the caller immediately. 

If a button is clicked before time expires, the number of the button is returned in the 
button_jnumber parameter. If the user does not click any mouse button before time expires, the 
function returns a button number of zero. 

For the mouse, button numbers 1, 2, an^ 3 represent the left, middle, and right buttons, respec¬ 
tively, when the buttons arc facing away from the user. 


7.4.2. awaitjsick — Wait for Pick Device 

await_pick waits for the user to pick an output primitive within a visible and detectable 
retained segment. 

await_pick(time, pick_number, segment_name, pick_id) 
int time; /* Time in microseconds to wait */ 

int pick^number; 
int *5egment_name; 
int *pick_id; 

await_pick waits for the user to click the left hand button on the mouse, or until the time 
specified by the time parameter expires. If the time argument is exactly zero, the function tests 
the button once, and if the button has been clicked, performs the pick operation. 
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If the button is clicked before time expires, the function returns the eegmentjname of the seg¬ 
ment that the pick device is pointing at, and the pick_td parameter is set to the value of the 
pick_id attribute of the primitive that was picked. If the user does not click any mouse button 
before time expires, or no segment is found vhere the user points, the function sets the 
segmentjname and piekjid parameters to rero. 

atDait_piek only searches those segments which are visible and detectable and appear on the echo 
surface of the specified PICK device. Primitives within a segment have bounded volume descrip¬ 
tors. The mouse cursor must be inside one of these 'extents’ in order for the segment and pick- 
id to be picked. If more than one segment is at the point, the segment with the highest value of 
the detectability attribute is returned. Detectability may be set to sero to prevent a segment 
from being picked. 

Errors returned from awaitjpich. 

• The specified pick device does not exist. 


7.4.3. await_keyb6ard — Wait for Input from the Keyboard 

await^keyboard waits for the user to type a line of input on the keyboard. 

await_keyboard(time, keyboard_number, input_8tring, length) 
lot time; /* Time in microseconds to wait */ 
int keyboard_number; 
char *input_8tring; 
int * length; 

awaitJfeyboard waits for the user to enter data at the keyboard, or until the time specified by 
the time parameter expires. If the time argument is exactly zero, the function tests once to see 
if a character has been typed, and then returns to the caller. 

If any data is entered at the keyboard before time expires, the function returns the typed char¬ 
acters in an array pointed to by input_3tring. The length of this character string is returned in 
tength. The string is null terminated. If the user does not enter any data before time expires, 
the function sets the iength parameter to zero. If a carriage-return or newline character is 
typed, the function returns with the input string containing a newline character as the last 
non-null character. 

Errors returned from await^kei/board: 

• The specified keyboard does not exist. 


7.4.4. await_stroke_2 — Wait for User to Draw a Line 

await_fitroke_8 waits for the user to draw a line, consisting of a list of points in normalized dev¬ 
ice coordinate space, using the mouse. 
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avrait_8troke_2(time, 8troke_number, arrayjsize, x_array, yjarray, number_pomts) 
int time; /* Time in microseconds to wait */ 
int stroke_number; /* Stroke device to wait for *f 
int arrayjsize; /* Maximum size of x and y arrays */ 

Boat x_array(|; 
float y_array(]; 

int ♦numberjpoints; /* Number of x, y coordinates actually read */ 

axDixitjttrokc waits for the user to draw a line using the mouse, or until the time specified by the 
time parameter expires. If the time argument is exactly zero, the function tests once to see if a 
line has been drawn, and then returns to the caller. 

The line starts at the current position of the locator, and finishes when the user clicks button 3 
on the pouse. When the function returns, the number of x, y coordinates actually read is 
returned in the numberjpoinU argument. When the number of points read equals arrayjsize 
the function returhs before time expires. 


7.4.6. await any, button get locator 2 — Read Locator When 
Button Clicked 

awaitjany_button_getJioeaior_B waits for the user to click any of the mouse buttons. When the 
button is clicked, the function returns the current normalized device coordinates of the locator. 

await_any_button_get_locator_2(time, locatorjaumber, button_number, x, y) 

Int time; /* Time in microseconds to wait *f 
int locator_number; /* Locator device to wait for */ 
int *button_number; /* Button which was clicked */ 
float *x, *y; /* Returned point in NDC */ 

awaitjany_huttonjgetJiocator^8 waits for the user to click any mouse button, or until the time 
specified by the time argument expires. If the lime argument is exactly zero, the function 
checks if any buttons have been clicked immediately and then retmns. 

If the time expires before the user has clicked any of the mouse buttons, the function returns a 
zero in the buttonjnumber argument. 

7.4.6. await_any_button_get_valuator — Read Valuator When 
Button Clicked 

await_any_button_get_vatuator waits for the user to click any of the mouse buttons, or for a 
specified time. When the button is clicked, the function returns the current value of the valua¬ 
tor: 


await_any_button_get_valuator{time, valuatorjuumber, button_number, value) 
int time; /* Time in microseconds to wait */ 
int valuatorjUumber; /* Valuator number to read from */ 

int *button_number; /* Button which was clicked */ 

float ♦value; /♦ Value of valuator */ 

await_any_button_yetj)aluator waits for the user to click any mouse button, or until the time 
specified by the time argument expires. If the time argument is exactly zero, the function 
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checks if any buttons have been clicked and then returns immediately. 

If the user clicks one of the mouse buttons, the function returns with the value of the valuator, 
and the number of the button which was clicked. If the time expires before the user has clicked 
any of the mouse buttons, the function returns a zero in the buttonjnumber argument. Move* 
ment of the mouse left or right lowers or raises the value of the valuator. 

7.4.7, get_mouse_state — Low Level Mouse Support (SunCore 
extension) 

get_moxuc_etatc reads the lov level mouse x, y, and button information corresponding to a par* 
ticular input device. The buttons are up'down encoded, and the location of the mouse is in nor^ 
malized device coordinates. 

get_mouse_state(device_class, device_number, x, y, buttons) 
int device class; j* PICK, STROKE, */ 

I* LOCATOR, VALUATOR, BUTTON */ 

int device_number; 
float ♦x, *y; 
int ’•‘buttons; 

Bit 0 of buUont is the right-hand mouse button. 

Bit 1 of buttons is the middle mouse button. 

Bit 2 of buttons is the left-hand mouse button. 

A zero bit means that the button is tip, while a one bit means that the button is doum. 


7.5. Inquiring Input Status Parameters 


7.5.1. inquire_echo — Obtain Type of Echo for Device 

inquire^eeho obtains the echo_type for the specified device. 

ittquire_echo(device_dass, device_number, echojtype) 

int device.class; /* PICK, KEYBOARD, STROKE, */ 

/* LOCATOR, VALUATOR, BUTTON */ 

int device_number; 
int '*echo_type; 


7.5.2* inquire_echojposition — Obtain Echo Reference Point 

inquire_echo_position obtains the position, in normalized device coordinates, of the echo refer¬ 
ence point for the specified device. 
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inquire_eclio_po8ition(device_class, device_number, echo_x» echo_y) 
int devicc_clas 0 ; /* PICK, KEYBOARD, STROKE, *f 

f* LOCATOR, VALUATOR, BUTTON */ 

lot device_number; 

float *echojc; /* x Coordinate of Echo Point */ 

float *echo_y; /* y Coordinate of Echo Point */ 


7.5.3. mquire_echo_surface — Obtain View Surface for Echo 


inquire_echo_surfaee obtains the viewing surface on which echoing is done for the specified dev¬ 
ice. 


inquire_echoj5urface(device_class, device_number, surface_name) 
int device_clas8; /* PICK, KEYBOARD, STROKE, */ 

/* LOCATOR, VALUATOR, BUTTON */ 

int device_number; 

struct vwsurf *8urface_name; 


7.5.4. inquire_locator_2 — Obtain Initial Locator Position 

inqttireJocator_S obtains the initial position of the specified locator in normalized device coordi¬ 
nates. 

inquire_locator_2(iocator_nuniber, x, y) 
int locatorjiumber; 
float ^'x; 
float *y; 


7.5.5. inquire_valuator — Obtain Value and Range for Valuator 
Device 

ingtiire_vatuator obtains the value and range for the specified valuator device. 

inquire_valuator(valuator_number, initial_value, low, high) 
int valuator_number; 
float *initial_value; 
float *low; 
float ^high; 


7.5.6. inquire_keyboard — Obtain Keyboard Parameters 

inquire_keybocird obtains the size of the character buffer, the initial character string, and the ini> 
tial character cursor for the specified keyboard. 
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inquire_keyboard(keyboard_number, buffer_8izc, initialjstring, initial_cursor_position) 
int keyboard_jiumber; 
int *buffer_8ize; 
char *initialj}tring; 
int *initial_cursor_j>osition; 


7*5.7. inquire^stroke — Obtain Stroke Device Parameters 

inquire_»troke obtains the buffer size, distance, and time parameters for the specified stroke dev¬ 
ice. 

inquirej»troke(stroke_number, buffer_8ize, distance, time) 
int stroke_number; /♦ device number */ 

int *bufferjsize; /* number of x, y points in buffer - not used*/ 
float *distance; /* minimum distance to move in NDC */ 
int *time; /* Not used */ 
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Programming Examples 


8.1. The Sun Workstation Factory 

This example provides a relatively simple programming example that nevertheless uses a goodly 
number of SunCore^s facilities. The example is called factory. It has a factory building with a 
smokestack and a cloud of smoke puffing out. Silicon chips move in at one end of the building, 
and Sun Workstations come out of the other end. 

Facilities displayed by this simple example include texturing, translation, scaling, and output 
clipping. The example is presented in pieces, with a narrative accompanying each of the pieces. 

8.1.1. Declarations and the Main Program 

Firot there i» on include of the file utereore.h which containo the definitions required for using the 
graphics package: 
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^include 

< usercore.h > 



/* Define segment numbers 

*/ 

#define 

FACTORY 

10 

^define 

CLOUD 

9 

^define 

WORKSTATION.! 

1 

#define 

WORKSTATION.2 

2 

^define 

WORKSTATION'S 

3 

^define 

CHIP.l 

4 

^define 

CHIP_2 

5 

#define 

CHIP 3 

6 


static float delta[) = {0.0, .025, 2*.025, 3*.025, 4*.025, 5*.025, 6*.025, 

7*.025, 8*.025, 9*.025, 10*.025, 11*.025, 12*.026}; 

static float redtex[) =» {.9981,.1765,.1334,.1334,.4667,.1334,.1334, 

.1334,.8001,.2667,.5334,.0}; 

static float grntex[] = {.5334,.2079,.5334,.5334,.5334,.5020,.5020, 
.3334,.2667,.6334,.5334,.2667}; 

static float blutex[] « {0.,0.,.4001,0.,.2118,.3529,.6471,.4001, 

.4001,.4001,.4001,.3882}; 

int bw2dd(); /* Device driver name for the Sun-2 */ 

/* monochrome display — sec appendix B */ 
struct vwsurf vsurf = DEFAULT_VWSURF(b'w2dd); 

/* The DEFAULT_VWSURF macro is defined */ 

/* in usercore.h ♦/ 

Then we have the main program: 

main() 

{ 

short i, pO, pi, p2, p3; 
int error; 
float scale; 
float clx, cly; 

The firat call in the program ia to initialize SunCore, with an appropriate exit if there ia an 
error returned: 

error = initialize_core(DYNAMICB, NOINPUT, TWOD); 
if (error) 
exit(O); 

Then we initialize and aelect a view aurface. Again, we exit if there waa an error returned: 

error = initialize_jview_surface{&vsurf, FALSE); 
error )= 8elect_viewjsurface(&v3urf); 
if (error) 
exit(l); 
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Then u>e eatabliak a vieteport and a window. Note that we can act clipping on output — thia ia a 
SunCore extenaion to the ACM Core. 

8ct_viewport_2(0.05, 0.95, 0.05, 0.7); 

8et_window(30.0, 225.0, 30.0, 225.0); 
set_output_clipping(TRUE); 

8et_windowjclipping(FALSE); 

Set up the color lookup table. 

define_colorJindices(&vsurf, 1, 12, redtex, gmtex, blutex); 

Now make a temporary aegment for a title and border. 

create_tempoTaiy_segment(); 
move_ab8_2(30., 30.); 

Hnejpel_2(0., 195.); 
line_rel_2(195., 0.); 
linejrel_2(0., -196.); 

Iinejrel_2(-196,, 0.); 

8etjcharprcci8ion(CHARAOTER); 

8et_cbar8ize(14., 14.); 

Bet_text_index( 1); 
moye_ab8_2(40., 200.); 
text(’’ SunCore"); 
cIo8e_temporaryjieginent(); 

Next we establiah a aegment for the factory. Thia aegment ia the aimpleat type, aince we perform 
no tranaformationa of any kind on it. 

8et_image_tran8formation_type(NONE); 
createj’etained_scgmcnt(FACTORY); 
factoi 7 ( 110 . 0 , 60.0); 
cIo8e_jretainedjsegment(); 

Next we eatabliah a aegment for the cloud above the factory. Thia aegment ia aubjectto acaling, ao 
we muat allow for tranaformationa. 

8et_imagejtran8formation_type(XFORM2); 
create_retained_8egment(GLOUD); 
raftP-WorWjtojndOUSO., 100., &clx, &cly); 
8eOegmentJiinage„transformation_2(CLOUD, 0.05, 0,1, 

0.0, clx, cly + 0.02); 
c]oud(0., 0.); 

cIo8e_retained_8egment(); 

Laatly, we eatabliah aegmenta for the chipa and the workatationa. The chipa and workatationa will 
be moving aeroaa the picture, ao theae aegmenta muat allow tranalation. 
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seOmagejtransformation_type(XLATE2); 

/* Do the Sun Workstation Segment */ 
createjretained_segment( WORKSTATIO N_1); 
sunws(160.0, 60.0); 
close_retained_segment(); 

createjretained_segment(WORKSTATION_2); 

8unw8(160.0, 60.0); 
close_ret ained_segment(); 

create_retained_segment(WORKSTATIONj3); 

8un’ws(160.0, 60.0); 
clo8e_retained_segment(); 

/* Do the Chip Segment */ 
create_retained^8egment(CHIP_l); 
chip(20.0, 70.0); 
clo8e_retained_segment(); 
create_j‘etained_8egment(CHIPj2); 
chip(20.0, 70.0); 
close_retained_segment(); 
create_jretained_8egment(CHIP_3); 
chip(20.0, 70.0); 
closejret ained_8egment(); 

Notice that we created the workttatiom all on top of each other, and alto all the ehipt on top of 
each other. The actual tpatial separation of the individual segments is handled in the main body 
of the animation code. 

Now we get to the body of the code which animates the picture. The outer for loop is done 100 
times. The calls on the translation routines make the chips and workstations move. The inner 
for loop makes the cloud groun 

pO = 0; pi ^ 4; p2 — 8; 
for (i—0; i<i00; i+ + ) { 

8et_segmentJmage_translate_2(WORKSTATION_l, delta[pO], 0.0); 
setjsegment_image_translate_2(WORKSTATION_2, delta[plj, 0.0); 
8et_8egment_image_trauslate_2(WORKSTATION_3, delta[p2], 0.0); 
set_segment_image_tran8late_2(CHIPj3, delta[p2], 0.0); 
set_8egmentJimage_translate_2(CHIPj2, delta[plj, 0.0); 
setj3egmentJmage_tran8late_2(CHIP_l, delta(p0], 0.0); 
p0++; pl+ + ; p2+-l-; 
lf(pO>ll) 
pO = 0; 
if (pi > 11) 
pi =0; 
if(p2 >ll) 

p2 = 0; 

for (8cale=0,l; 8cale<1.0; scale + «= 0.2) 

3etjsegment_image_transformation_2(CLOUD, 0.5 * scale, scale, 

0.0, clx, cly + scale * 0.2); 

} 

Finally, when everything is done, we deselect the view surface, and terminate SunCore: 
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deselect__view_5urface( fevsurf); 
terminate_core(); 

} j* End of the main program */ 

The remainder of the demonstration program consists of the subroutines which fill in the details 
in the indiyiduai segments. 


8.1.2. The factory Drawing Function 

Firtt, here are the coordinates for the outline of the factory itself. 

static float factdx(] = {0.0, 0.0, 8.0, 2.0, 3.0, 2.0, 3.0, 1.0, 3.0, 1.0, 17.0, 0.0, -40.0}; 
static float factdy[] — {0.0, 20.0, 0.0, 20.0, 0.0, -20.0, 0.0, 15.0, 0.0, -15.0, 0.0, -20.0, 0.0}; 

The next set of declarations describe the outline of the windows in the factory: 

static float winddx[] =» {0.0, 0.0, 10.0, 0.0, -10.0}; 
static float winddyf] {0.0, 5.0, 0.0, -5.0, 0.0}; 
static int black 3; 

static int brick 1; 

Now we have the actual code of the factory drawing routine itself. 

factory(x0, yO) 

float xO, 

{ 

The xO and yO arguments to the factory function describe the absolute position in world coordi¬ 
nates at which the factory should appear. The actual outline of the factory is described by the 
array of coordinates declared above. 

set_fill_index(brick); 

move_ab8_2(x0, yO); /* Move to appropriate position ♦/ 
polygonjreL2(fact^, factdy, 12); /* Draw the factory outline */ 

Now we draw the voindows within the factory: 

8etjfiUJindex(black); 

move_rel_2(5.0, 10.0); /* Move to position of first window */ 

polygottjreIj2(winddx, winddy, 4); f* and draw the window *f 

move_rc!_2( 15.0, 0.0); f* Move to position of second window ♦/ 
poIygon_reI_2(winddx, winddy, 4); /* and draw the window ♦/ 

8etjll_index(l); /* reset fill index */ 

} j* End of the factory drawing function */ 

The next function is the one which draws the Sun Workstations within the workstation seg¬ 
ment. 


Revision ^ ^ January 1984 


8-5 





Programming Examples 


SunCore Reference Manual 


8.1.3. The Workstation Drawing Function 

The declarations below describe the outline of the Sun Workstation. Tube describes the screen, 
Case describes the outer outline of the case, bate describes the base of the Workstation, and 
keybd describes the appearance of the keyboard: 

static float tubex{] = {0.0, 5.0, 0.0, -5.0}; 
static float tubey[] *= {5.0, 0.0, -5.0, 0.0); 

static float casex[] ~ (1.0, 7.0, 1.0, 1.0, -1.0, -7.0, -1.0}; 
static float casey(j *=« {7.0, 0.0, -7.0, 1.0, 7.0, 0.0, -1.0}; 

static float basex[] =» {9.0, -1.0, -1.0, -5.0, -1.0}; 
static float basey[] =* {0.0, 0.0, -2.0, 0.0, 2.0}; 

static float keybdx[] == {0.0, 10.0, 3.0, 0.0, -10.0, -3.0, 10.0, 3.0}; 
static float keybdyjj = {-1.0, 0.0, 2.0, 2.0, 0.0, -3.0, 0.0, 3.0}; 


8unws(x0, yO) 
float xO, yO; 

{ 


Then aU we have to do it move to the coordinateo that were supplied as function arguments, and 
draw the lines: 

move_abs_2(x0+ 5.0, y0+ 8.0); /♦ Move to the position given */ 

polyline_rel_2(tubex, tubey, 4); /* Draw the tube */ 


move_rel_2(-2.0, -1.0); 

polyline_rel_2(casex, casey, 7); /* Draw the case ♦/ 


move_rel_2(-1.0, -7.0); 

polyline_rel_2(basex, basey, 5); /* Draw the base */ 


move_ab8_2(x0, y0+ 1.0); 

polyline_rel_2(keybdx, keybdy, 8); /* Draw the keyboard */ 

} /* End of the Workstation Drawing Function */ 


8.1.4. The Chip Drawing Function 

The declarations below describe the outline of the chips. Plasti describes the outline of the chip 
itself, while lead describes the outline of the leads on the chip: 
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static float plastixf] = {0.0,16.0, 0.0, -16.0}; 
static float plastiy[] = {4.0, 0.0, -4.0, 0.0}; 

static float leadx[] => {-1.0, 2.0, -1.0, 0.0}; 
static float leadylj « {2.0, 0.0, -2.0, -4.0}; 

clup(x0, yO) 
float xO, yO; 

{ 

short i; 

Then all we have to do la move to the coordinated that were tupplied a$ function arguments, and 
draw the lines: 

set_rasterop(XORROP); 

move_ab8_2(x0, yO); /* Move to appropriate position */ 

polyline_rel_2(plastix, plastiy, 4); /* Draw the chip ♦ / 

movejreL2(2.0, 1.0); 

for (i*=*0; i<5; i+ + ) { /* Draw the leads on the chip */ 

polyline_relj2(lea^, leady, 4); 
movcjel_2(3.0, 4.0); 

) 

8ctj:asterop(NORMAL); /* reset rasterop */ 

} /* End of the chip drawing function */ 


8.1.5. The Cloud Drawing Function 

The last function is the one that draws the cloud. The cloud function is easy: all we have to 
do is draw its outline. The actual scaling of the cloud is done in the main program. 

The declaratioM below describe the outline of the cloud: 

static float cloudx[] — {0.0, 8.0, -8.0, -4.0, 2.0, 14.0, 8.0, 0.0,12.0, 8.0, 4.0, 0.0, 

-10.0, 10.0, 4.0, -2.0, -6.0, -12.0, -6.0, -12.0, -10.0); 
static float cloudy[] *» {12.0, 8.0, 2.0, 6.0, 6.0, 10.0, -4.0, -6.0, 10.0, 0.0, -4.0, 

-10.0, -10.0, -2.0, -6.0, -8.0, -4.0, 0.0, 4.0, -8.0, 4.0}; 


cloud(x0, yO) 
float xO, yO; 

{ 

Then all we have to do is move to the coordinates that were supplied as function arguments, and 
draw the lines: 

move_abs_2(x0, yO); 
polylinejrel_2(cloudx, cloudy, 21); 

} f* End of the cloud drawing function *( 
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Deviations from ACM SIGGRAPH Core 


This appendix points out specific differences between the SunCore graphics package and the 
ACM SIGGRAPH Core Specification. In addition to differences noted here, SunCore has 
numerous extensions to the ACM Core which are documented in the main body of this manual. 

A.!* Unimplemented Functions 

Here is a list of those functions which SunCore does not implement: 

Table A-1: Unimplemented Primitive Attribute Functions 


• tet^charjuat 


Primitive Attribute Functions 


• tnquiTC_charju9t 


Table A-2: Unimplemented Synchronous Input Functions 


Synchronous Input Functions 

• 

imtiai{ze_gr oup 

• 

terminate^oup 

• 

await_atroke_S 

• 

await_anyJ>utton_getJocator_S 

• 

iet_echo_aegment 

• 

aetjptek 

• 

aetjbutton 

• 

aet_aUJbuttona 

• 

$etJloeator_3 

• 

aet_locport_2 

- • 

setJloeport^S 

• 

tn9Uire_inpuf_capa6iYifte« 

• 

mquirejlnput_device_characteri»ttea 

• 

inquire_a tr oke_^dimen»i on 

• 

mquireJloeator_dimension 

• 

inquirejpick 

• 

inquire_button 

• 

inquireJlocator_S 

• 

• 

inquire_heport_3 
inquirejteh oji cgm enta 

• 

mquiTe_locport_S 


Revision ^ of 7 January 1984 


A-1 













Deviations from ACM SIGGRAPH Core 


SunCore Reference Manual 


Table A-3: Unimplemented Asynchronous Input Functions 


Asynchronous Input Functions 

• 

enablc^device 

• enable^roup 

• 

diiabU^device 

• duable^oup 

• 

di«abte_att 

• read_locator_8 

• 

readjlocator_3 

• roadjoaiuator 

• 

await_eveni 

• flu8k_Jteviee_evcnt8 

• 

fluth_j}r 0 up_evenU 

• flu8h_aU_event8 

m 

(Utocittte 

• di 8 a 880 ciatc 

m 

die asi ociate_device 

• di 8 aa 80 ciate_gr<ntp 

• 

di$a88oeiate^aU 

• Jiyiek_data 

• 

gctjteyb oar d_Jlata 

• get_fitroke_data__8 

• 

get_8troke_data_S 

• getJlocator_data_8 

• 

getJlocator_datajS 

• get_valuator^data 

• 

inqmre_device_a88oeiation8 

• inquire_devicc_8tatu8 


Table A-4: Unimplemented Control Functions 


Control Functions 

• 1 «^if c_o utput_e ap a6i7tfics 

• inquire_8elected_8ur/ace8 

• aetjimmediate^viaibilitg 

• maA:c_j»fct«re_carr«nt 

• inquirc_j:ontrotj8tatU8 

• aetjoiaibiUtiea 

• log_error 



Table A-5: Unimplemented Escape Functions 



Escape Functions 

• eacape 


• inqn{rc_eaeape 

. Other Differences 




Text: SunCore does not kave the charplane primitive attribute; instead, the charpath, 

charup, and charspace attributes are used to specify text orientation as described in the manual. 
The current release of SunCore has no STROKE precision text and no text justification. The 
inqnire_tezt_extent_2 and inquircJtext_extent_S functions do not take a view surface name as an 
argument. The text enquiry functions only return meaningful values when the current charprc- 
cision attribute is CHARACTER. 
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Raster Ebctensions; SunCore contains several of the proposed raster extensions to the 
ACM Core and other raster functions. Thus there are no color or intensity primitive attributes. 
Instead a color lookup table model is used. There are several primitive attributes vrhich are 
indices into lookup tables. In addition, hidden surfaces are supported on color view surfaces. 
This requires a second parameter to the mitialize_view_turface function. 

Miscellaneous: SunCore adds these functions: 

tetjimageJtramlatejS, 

inquire_image_tranBlaU_jSf 

4 et_8egmentjimage_Jran»late_3, 

inquire_»egmcntjimageJtran»latcjS. 

The functions: 
s et_pnm$tive_attributeB_S, 

Bet_primitivc_attribute$_S, 
inquire_primitive_attribute8_8f and 
inquire_primitive_attributes_S 

are replaced by the functions tet_primitive_attributet and inqutre_primitive_attributet, which are 
equivalent to the 3*D functions. 

Default values for many SunCore system parameters differ from those of the ACM Core. 

There are restrictions on 8et_world^eoordinate_matrix_2 and iet_world_coordinatc_matrix_S as 
described in the manual. 

As described in the manual, some of the echo types for input functions in the ACM Core are 
not implemented. 

The marker symbol primitive attribute deviates from the ACM Core as described in the 
manual. 

Batching of updates only applies to dynamic segment attributes as described in the manual. 

View surfaces initialised for hidden-surface elimination do not support dynamic segment attri¬ 
butes of highlighting, transformation, or translation. initialize_vtew_Burface can optionally 
suppress clearing the view surface when it is initialized. 
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SunCore View Surfaces 


SunCore supports several types of view surfaces and multiple simultaneous instances of any 
type, subject to the hardware resources of the workstation on which a SunCore program is 
being run. The current release allows up to five view surfaces to be active at any time. This 
appendix ^ves implementation details of SunCore view surfaces and provides information on 
initializing them. 


B.l. The vwsurf Structure 

View surface names in SunCore are structures. The following declaration and definitions are 
contained in the header file /usr/tnc/ude/uscrcorc.A; 

#define DBVNAMESIZE 20 

struct vwsurf { 

char sereennamepEVNAMESIZE]; 

char windowttame[DEVNAMESIZE]; 

int windowfd; 

int (*ddX); 

int instance; 

int cmapsize; 

char cmapnamepEVNAMESIZE]; 
int flags; 
char ♦♦ptr; 

}; 

#define NULL.VWSURF 0, 0, 0, 0, 0, 0} 

#define DEFAULT_VWSURF(ddname) 0, ddname, 0, 0, 0, 0} 

#define VWSURF.NEWFLG 1 

After initialization via the function imtiaUze_view_surface, a vwsurf structure represents a 
specific instantiation of a particular type of view surface. The elements of the vwsurf structure 
completely characterize that instantiation and/or provide information used to initialize the view 
surface. This appendix refers to members of the vwsurf structure using the standard C notar 
tion, as if the declaration 

struct vwsurf vwsurf; 
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had been given. 
vwtwf.tcreenname 

is a character string which is the name of the physical device on which the view surface 
appears (for example, ’’/dev/cgoneO"). 

vtp» urf. win downame 

is a character string which is the name of a window device which has been opened for 
display of the output primitives directed to the view surface (for example, ”/dev/winlO”); 

vwsur/.windowfd 

is the file descriptor corresponding to this device. Since, for all current SunCore view sur¬ 
face types, output display and input device echoing are accomplished through window sys¬ 
tem routines, these members of the structure are valid even for raw output devices. 

vwsurf.dd 

is the name of the device-independent/device-dependent interface routine through which 
graphics output to the view surface will pass. This routine defines the view surface type. 
The current SunCore view surface types are described below. 

vwsurf.instanee 

identifies the instantiation of a view surface type. It should be set to 0 prior to calling 
initialize_view_iur/oee. SunCore will set this value appropriately if the initialization is 
successful. 

vw» urf. emapt izt 

defines the size of the color lookup table for the view stirface, and the character string 
vwturf.ctnapnamt gives its name, which can be used to share a color map between two or 
more view surfaces on the same physical device. These elements of the vwsurf structure are 
used only for view surfaces on color devices. Their use is described more fully below. 

vwtwf.flaga 

is a field of one-bit flags. Currently, only one flag, VWSURF_NEWFLG, is defined; this flag is 
described below. 

vwturf.ptr 

is a pointer to an array of character pointers. The array should be terminated by a null 
pointer. The strings pointed to by the array contain optional information which may be 
used to initialize the view surface. Details are provided below. 

B.2. View Surface Types 

A view surface type in SunCore is the name of the driver routine for the device- 
independent/device-dependent interface. The name of the routine corresponding to the desired 
view surface type should be put into vwiurf.dd prior to calling initiaiize_view^surface (see the 
programming examples in Chapters 1 and 8). 

The current release of SunCore has five view surface types: 
bwldd 

The Sun-1 monochrome bitmap display used as a raw device. 
bw2dd 

The Sun-2 monochrome bitmap display used as a raw device. 
cgldd 

The Sun Workstation color graphics display used as a raw device. 
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pixwindd 

A monochrome (one-bit deep) graphics window within the Suntools window environment. 
This window may appear on either a color or monochrome display. 

cgpixwindd 

A color graphics window within the Suntools window environment. This window must 
appear on a color display. 

Only view surfaces types cgldd and cgpixtvindd support hidden surface removal. 

The term ‘raw device’ above implies that the physical device specified by vwsurf.tcreenname is 
used completely and only for display of graphics output directed to one view surface. This 
allows somewhat more efficient display of output primitives. It also implies that the user has 
not started up a Suntools window environment using the device as a desktop. 

Low-level device-dependent routines are not part of SunCore. For the sake of efficiency, such 
routines are necessary for some applications. The Programmer’s Reference Manual for the Sun 
Window System contains information on low-level routines corresponding to bwldd, bwBdd, 
and egldd (the ‘pixrect* level) and pixwindd and egpixmndd (the ‘pixwin’ level). 

B,3. Choosing a View Surface Type within an Application Pro¬ 
gram 

It may be desirable to write application programs which use different view surface types depend¬ 
ing on the environment. The next two subsections provide examples of ways to do this. The 
next subsection illustrates using a Shell vanable, and the subsection after that uses the 
getjuievjiurfaee function to do the job in a more general way. 

B.3.1. Using SHell Variables to Determine the Environment 

Examining a Shell environment variable is one way to determine which environment a program 
is running in. The following example illustrates using either a bwSdd (raw Sun-2 monochrome 
display) or a pixwindd (monochrome window) view surface depending on whether the user is 
currently in the Suntools window environment. The WINDOW_ME environment variable is nor¬ 
mally defined in the user’s environment if and only if the window system is being used. 
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* an example of selecting a view surface 

* depending on tlie current environment 

*/ 

int bw2dd(); 

struct vwsurf rawsurface = DEFAULT_VWSURF(bw2dd); 
int pixwinddO; 

struct vwsurf windowsurface = DEFAULT_VWSURF(pixwindd); 
main() 

struct vwsurf ^surface, *get_8urface(); 


surface =*■ get_surface(); 
initiaU*e_vicw_surface(8urface, FALSE); 
select_view_surface(8urface); 


} 

struct vwsurf *get_surface() /* function to return pointer */ 
{ /* to appropriate view surface */ 

if (getenv(”WlNDOW3iE”)) 
retiirn( fewindowsurface); 

else 

return( ferawsurface); 

} 


B*3.2. The get_view_8urface Function 

The SunCore library includes the get^view_twface function which a programmer can use to set 
up a view surface structure using information from command>line arguments and the environ¬ 
ment. A complete listing of get_vicw_swface appears at the end of this section. 
getjview_surfaee has the following declarations for C, FORTRAN, and Pascal: 
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C Declaration: 

get_view_8nrface(vsptr, argv) 
struct Twsurf *ysptr; 
char **argv; 


FORTRAN Declaration: 

getview8urface(vw8urf, argv) 
integer vw8urf(VWSURFSIZE) 
integer argv(*) 



Pascal Declaration: 

getTiew8urface(var surfacename: vwsurf; var argv: iarr): integer; external; 

The elements of argv are pointers to null-terminated strings which are extracted from the com¬ 
mand line that started the application program. Since FORTRAN and Pascal do not have 
pointer types, integer arrays are used instead. 

The programmer is responsible for setting up the argv array in FORTRAN and Pascal programs. 
In the simple case where there are no command-line arguments, it is only necessary to set the 
second element of the argv array to tero — the first element of the array is assumed to point to 
the name of the program being run. The following fragment of O code illustrates the use of 
get_vtew^6urfaee for C programs: 

maln(argc, argv) 

int argc; 
char •«argv; 

{ 


struct vwsurf vwsurf; 


code 


If (get_view_8nrface(&vw8urf, argv)) 
exit(l); 

initialize_view_surface(&vwsurf, FALSE)) 


more code 
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getjviewjswfaee returns zero (0) if it succeeds and non-zero otherwise. The vwturf structure 
will have vwturf*dd and possibly vwturf,tereennamc set to appropriate yalues. Other elements 
of the structure will be null — the programmer may modify them to suit the application, but it 
is not necessary. 

The only command-line option that getjviewjturface currently recognizes is the 
—d ditplag_device 

option, where ditplay_devtce is the name of the physical display device {/dev/fb or fdev/egoneO 
for example). The vwturf structure will be set up to run on this device, gtt_vieu>jturface also 
determines if the window system is running on the device, and chooses vwturf,dd appropriately. 

Using get_view_turfaee has a disadvantage in that since it refers to all five SunCore types of 
view surfaces, any program using it will get the code for all five device-independent/de vice¬ 
dependent driver routines linked in. For this reason, the code for get^v{ew_turface is included 
here, SunCore programmers may wish to tailor a version of this code for particular machine 
configurations and applications. 

The code of getjviewjturfaee contains calls on severaf functions from Ubtunwindow,a — the 
window system library. Details of these routines can be found in the Programmer’s Reference 
Manual for the Sun Window Syttem. 

/* 

get_view_surface -- Determines from command-line arguments and 
the environment a reasonable view surface 
for a SunCore program to run on. 

*/ 

#include <sys/file.h> 

#include <sys/ioctl,h> 

#include <sun/fbio,h> 

^include <stdio.h> 

#include <8unwindow/window_hs«h> 

^include <usercore,h> 

int bwldd(); /* All five device-independent/device-dependent ♦/ 

int bw2dd(); /* routines are referenced in this function. */ 

int cgldd(); /* This means the linker will pull in all of them */ 

int pixwinddO; 
int cgpixwinddO; 

static struct vwsiuf nullvs » NULL^VWSURP; 

static char *devchk; 
static int devhaswindows; 

int get_view_surface(vsptr, argv) 
struct vwsurf *vsptr; 
char **argv; 

{ 

int devfnd, fd, chkdevhaswindows(); 
char *wptr, dev[DEVNAMESIZE], *getenv(); 
struct screen screen; 
struct fbtype fbtype; 
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♦vsptr = ttullvs; 
devfnd «= FALSE; 
if (argv) 

/* . 

If command-tine arguments passed, process them using 
winjnitscreenfromargT (see the Programmer's Reference Manual 
for the Sun Window System). The only option used by 
get_view_8ttrface is the -d option, allowing the user to 
specify the display device on which to run. 

*/ 

{ 

winJnitscreenfromargv(&scrcen, argv); 
if (screen.8cr_fbname[0] !=» ’\0’) 

f* -d option was found */ 
devfnd = TRUE; 

8trncpy(dev, 8creen.scr_fbname, DEVNAMESIZE); 

/* 

Check to see if this device has a window system 
running on it. If so devhaswindows will be TRUE 
following the call to win_enumall. win_enumall is 
a function in libsunwindow.a. It takes a function 
as its argument, and applies this function to every 
window being displayed on any screen by the window 
system. To do this it opens each window and passes 
the windowfd to the function. The enumeration 
continues until all windows have been tried or the 
function returns TRUE. 

i i 

devchk = afcf | 
devhaswindows = FALSE; 
win enumall(chkdevhaswindows); 

} 

} 

if (Idevfnd) 

/* No -d option was specified ♦/ 
if (wptr « getenv(”WINDOW_ME’’)) 

{ 

/* - 

Running in the window system. Find the device from 
which this program was started. 

*/ 

devhaswindows =» TRUE; 

if ((fd =» open(wptr, 0_RDWR, 0)) < 0) 

fprintf(stderr, ”get_view_surface: Can’t open %a\n”, 
wptr); 
return(l); 

winjscreenget(fd, fescreen); 
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c!ose(fd); 

strncpy(dev, screett.scr_fbnanie, DEVNAMESIZE); 

} 


9 

Not running in the window system. Assume device is 
/dev/fb. 

*/ 

devhaswindows *= FALSE; 

8trncpy(dev, ”/dev/fb", DEVNAMESIZE); 

/* Now have device name. Find device type, */ 
if ((fd^= open(dev, 0_RDWR, 0)) < 0) 

fprintf(stderr, ’’get_viewj5urface: Can’t open %s\n”, dev); 
ret\irn(l); 

if (ioctl(fd, FBIOGTYPE, fefbtype) *== -1) 

fprintf(stdcrr, ’’get_vicw_surfacc: ioctl FBIOGTYPE failed on %9\n”, 
dev); 
close(fd); 
ret\irn(l); 

} 

clo8e(fd); 

/* Now have device type and know if window system is running on it. */ 
if (devhaswindows) 

8witch(fbty pe .fb_type) 

{ 

case FBTYPE_SUN1BW: 
case FBTYPE_SUN2BW: 

vsptr->dd = pixwindd; 
break; 

case FBTYPE_SUNlCOLOR: 
vsptr->dd = cgpixwindd; 
break; 
default: 

fprintf(stderr, ” get_view_8urface: %3 is unknown fbtype\n’’, 
dev); 
retum(l); 

} 

else 

switch(fbtype.fb_type) 

{ 

case FBTYPE_SUN1BW: 
vsptr->dd — bwldd; 
brc&lc* 

case FBTYPE_SUN2BW: 

Ysptr->dd = bw2dd; 
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break; 

case FBTYPEJSUNICOLOR: 
vsptr->dd » cgldd; 
break; 
default; 

fprintf(stderr, "get_viewjsurface: %8 is unknown fbtype\n”, 
dev); 
return(l); 

} 

/* Now SunCore device driver pointer is set up. */ 
if (Idevhaswindows |] devfnd) 

/♦ 

If no window system on device or -d option was specified, 
tell SunCore which device. Otherwise, let SunCore figure 
out the device itself from WINDOW_GFX so the default 
window will be used if desired. 

*/ 

stmcpy(vsptr->screenname, dev, DEVNAMESIZE); 
retuni(O); 

} 

static int chkdevhaswindow8(windowfd) 
int windowfd; 

{ 

struct screen windowscreen; 

winjscreenget(windowfd, ftwindowscreen); 
if (stremp(devchk, windowscreen.scrjfbname) 0) 

{ 

/* 

If this window is on the display device we are checking, set 
the flag TRUE. Return TRUE to terminate the enumeration. 

*/ 

devhaswindows = TRUE; 
return(TRUE); 

retum(EALSE); 

} 


B.4. Specifying a View Surface for Initialization 

It is not necessary to specify every member of the vwiurf structure in order to initialize the view 
surface. If only vtP9urf,dd is specified, SunCore will try to obtain a view surface of the 
specified type according to a default sequence. A statically allocated vwsurf structure may be 
set up to use this default by initializing the structure via the DEFAULT_VWSURF macro defined 
in utercore»h. This is a compile-time initialization. The iiser may exercise finer control over 
view surfaces by setting other elements of the structure as described below. Any members 
which are not specified by the user should be set to zero (the integer 0, the NULL pointer, or an 
empty string, as appropriate). 
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B.4.1. View Surface Specification for Raw Devices 

The default action for obtaining a new view surface of a raw device type is to try to open a 
sequence of devices until one is found which is of the right type and is not already being used. 
The sequence always starts with ’’/dev/fb”. Then the following names arc tried depending on 
the view surface type: 

bwldd - "/dev/bwoneO", "/dev/bwonel”, ”/dev/bwone9” 
bw2dd - ’’/dev/bwtwoO”, ”/dev/bwtwol”, "/dev/bwtwoO” 
cgldd - ”/dev/cgoneO*,’’/dev/cgonel”, "/dev/cgoneO” 

If none of the names in the sequence can be successfully opened and verified to be of the correct 
type and not already in use, initiaUze_j}iew_surface fails. 

If the qlier wishes to specify a particular physical device for a view surface, he may set 
vwiurf.icreenname to be the device name of that device. The same steps will be taken to try to 
open the device as for each name in the default sequence. However, if these steps fail, no other 
names will be tried, and the initialization will fail. 

vwsurf.cmapname and vwsur/.cmapsize are only used for color view surfaces. For cgldd, 
vwtvrf.emapzize is set to 256. If vwaurf.cmapname is specified, this name is used as the name of 
the color map; otherwise SunCore will provide a unique name. 

No flags are currently defined for use with raw devices. 

vwzurf.ptr provides a mechanism for passing optional initialization data to SunCore. In the 
case of raw devices, one such option is currently available — the passing of information about 
the adjacencies of physical screens. When the user creates a Suntools window environment on a 
screen, he is also responsible for specifying the relationship of that screen to other screens also 
running Suntools for purposes of tracking the mouse across multiple screens. The adja- 
centicrecM command may be used to do this (see the User’s Manual for the Sun UNIX Sys* 
tern). However, when a SunCore program initializes a new view surface on a raw screen, the 
user will not previously have been able to inform the system of this adjacency because the new 
screen was previously not in use. vwturf.ptr may be used to pass adjacency information for the 
new screen. 

If vwturf.ptr is not NULL,, it should point to an array of character pointers. Only the first 
pointer in this array will be used. It should point to a string which is the pathname of a file 
containing information about the adjacencies of physical display devices. When the user sets up 
his display devices on his desk he may create a file describing the layout of these devices. For 
example, the following lines describe a system with two screens, the console frame buffer on the 
left (which might ,b|S either a Sun-1 or a Sun-2 monochrome bitmap display) and a Sun color 
graphics display od the right: 

/dev/fb 

R: /dev/cgoneO 
/dev/cgoneO 
L: /dev/fb 

By convention, /dev/fb is the console frame buffer and /dev/cgoneO is the first Sun color graph¬ 
ics display on a system. For each display device in the system, there should be one line giving 
its name, followed by several lines giving the directions and names of all adjacent screens. Thus 
all four lines above are necessary, not just the first two. Directions may be indicated as R, L, 
T, and B for right, left, top, and bottom, or as N, S, E, and W for north, south, east, and west. 
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B.4.2* View Surface Specification for Window Devices 

The default action for obtaining a new view surface of type pixwindd or cgptxwindd is to first 
test whether the window referred to by the Shell environment variable WINDOW_GFX is already 
in use as a view surface. If not, a blanket window is inserted over the WINDOW_GFX window 
and this blanket window becomes the view surface. If WINDOW_GFX has already been used in 
this manner, the program /usr/suntool/coretool is invoked to create a new window on the same 
physical display device as WINDOW.GFX. This new window becomes the view surface. Thus, if a 
SunCore program is run from the tty subwindow of a Graphics Tool, the first default view sur¬ 
face will occupy the display space covered by the graphics subwindow of the tool. Subsequent 
default view surfaces will appear as graphics windows, each within a separate Core Tool on the 
same screen as the Graphics Tool. 

This default action may be circumvented in two ways. If vmurf.flags has the VWSURF_NEWFLG 
set, no attempt is made to take over WINDOW_GFX. A new window within a Core Tool is opened 
on the same screen as WINDOW_GFX If vwturf.tcreennamc is non-empty, a new window within a 
Core Tool is opened on the screen specified by vwturf.Bcrccnname, provided this device exists 
and has a Suntools window environment running on it. 

For view surfaces of type egpixwindd, vwBurf.cmaptize and vwsurf.cmapname provide a means 
of specifying and sharing color maps. The color map facilities of the Sun Window System are 
used to control color maps for cgptxwindd view surfaces (see the Programmer’s Reference 
Manual for the Sun \^^ndow System for details). The user may specify a color map size of 0, in 
which case a color map of length 2 will be used. Otherwise, vw^ur/.cmapsize should be a power 
of 2 between 2 and 256. The user may specify a null color map name, in which case SunCore 
will provide a unique name. Otherwise, SunCore wilt check vwturf.cmapname against the 
names of the color maps for all windows currently displayed on the physical device on which the 
new view surface is to appear. If a matching name is found, that color map will be used (even if 
its size differs from vwBurf^tmapsize) and this map is shared among all windows on the device 
which reference that name. If the user specified a null name or the specified name does not 
match any current window’s color map name, a new color map is allocated with the given size. 
The indices for each egpixwindd view surface's color map run from 0 to vw»wf,emap$ize-l. The 
current release of tie Sun Window System enforces the restrictions that entry 0 of the color 
map is the background color for the desktop containing the window and entry 
vwaurf^cmaptize-l is the foreground color. The default background color for a desktop is 
white, and the default foreground color is black. 

Currently, one optional string of initialization data may be passed to initiatize_j}iew_jsurface. If 
vw 9 urf,ptr is non-^NULLi it should point to an array of character pointers, only the first of 
which will be used. The pointer should point to a string containing position and size informa¬ 
tion for a Core Tool which may be started up to provide a window for the new view surface. (If 
the WINDOW_GFX window is tak^ over by this new view surface and thus no Core Tool is 
started^ the string will be ignored.) The string should consist of nine integers, separated by 
commas: 

” nl,nt,nw,nh,il,it,iw,ih,r 

ni, and n^ give the initial position of the top left comer of the Core Tool in its normal form, nw 
and nh give the initial width and height. The numbers are given in screen coordinates, where 
(0, 0) is the upper left corner, il, it, iw, and ih give the same initial information for the iconic 
form of the tool. I is a boolean flag which should be non-zero if the tool is to be started in its 
iconic form. 
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B.5. Input Considerations 

SunCore uses window system routines to obtain user input from the keyboard and mouse, no 
matter what mix of raw device view surfaces and window device view surfaces the user has ini¬ 
tialized. For purposes of input, a raw device view surface behaves just like a window device 
view surface; it exists as a window within the window system’s data structures, and the user 
may direct input to the window simply by positioning the mouse over it. The facts that win¬ 
dow system input is directed to different windows depending on the location of the mouse and 
that the mouse position in the window system is reported in the coordinates of the window 
underlying the mouse have implications for the SunCore input functions. 

For SunCore programs which are invoked from a window within the Suntools window environ¬ 
ment, whenever the KEYBOARD device is initialized, await_keyboard will return characters typed 
when the mouse is located over any initialized view surface (belonging to a single user process) 
or over the tty subwindow from which the program was started. For programs run from out¬ 
side a window environment, awaitjceyboard will return all characters typed on the keyboard, 
provided the KEYBOARD device is initialized. 

The ACM Core specification defines input and output to be completely orthogonal functions. 
Thus, it is possible to initialize a locator device and read from it without ever initializing a view 
surface. SunCore uses the mouse as the LOCATOR, STROKE, PICK, VALUATOR, and BUTTON 
devices. The only way SunCore can obtain mouse position and button click information to 
emulate these logical devices is to take input from a window. SunCore will return valid data 
in response to input requests for the LOCATOR, STROKE, PICK, and VALUATOR devices only when 
the user has associated these devices with an initialized view surface via the $et_ccho_surface 
function. Because all SunCore view surfaces are instantiations of generic view surface types, 
there is no default echo surface for any input device. The tet_echo_surfacc function will accept 
a NULL pointer as its sttrface_name argument to allow the programmer to end the association of 
an input device with a view surface. Any input device may be echoed on any view surface 
independently of any other input device. 

The input functions await_any_button_yetjlocator _04 await_8troke_S, awaitjpiek, and 
ttwait^anyjbutton_get_,valuator will only use mouse input which the user directs to the window 
which is the echo surface for the indicated LOCATOR, STROKE, PICK, or VALUATOR device. This 
includes both position and button click input, so that the functions which are terminated by 
button clicks will terminate only when a button click occurs within the proper window (or a 
timeout occurs). Which buttons are listened to is still controlled by individually initializing or 
terminating each BUTTON device. 

The user may also use 8 ct_eeho_$vrfac9 to ckoose from which window button clicks should be 
reported for a BUTTON device when the await_button function is called; alternatively, if the echo 
surface for a BUTTON device is NULL, awaitjbutton will check for button clicks from any view 
surface associated with a LOCATOR, STROKE, PICK, or VALUATOR device. 

Note that the resolution obtained from a LOCATOR, STROKE, PICK, or VALUATOR device is lim¬ 
ited by the width and/or height of its echo surface window, since mouse position information is 
provided by window system input routines in terms of window coordinates. 


B.6. Notes on Window Device View Surfaces 

Graphics primitives drawn on a view surface as part of a temporary segment normally remain 
visible on the view surface until a new-frame action occurs. For view surfaces which are win¬ 
dows within the Suntools window environment, several user actions can cause the view surface 
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to be redrawn. Such actions include stretching the enclosing tool, exposing a previously 
obscured portion of the tool, and changing from the iconic form of the tool to the normal form. 
When the view surface is redraivn in this manner, all output primitives which previously 
appeared as part of temporary segments will disappear. 

When a SunCore program is run from a Shell Tool, WINDOW_Grx is normally set to be the 
tool’s tty subwindow. If this window is taken over and blanketed to serve as a view surface, 
output directed to the tty subwindow (for example, stdout and stderr, including SonCore error 
messages) will not be visible because the blanket window obscures the tty subwindow. When 
the program terminates or the view surface is terminated, any portion of this output which has 
not scrolled out of the subwindow will be visible. The fact that the tty subwindow is obscured 
also means that there is no way to type characters to that window, so that stdin will never see 
any input. However, if the KEYBOARD device is initialized, special characters, such as interrupt 
and suspend, typed to the blanket window will be recognized and will have their normal effect 
on the user process. 
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Appendix C 


Using SunCore with Fortran-77 Programs 


All functions provided in SunCore may be called from PORTRAN-77 programs by linking them 
with the /usr//t6//t6eorc77«o library. This is done by using the /77 compiler with a command 
line such as: 

% f77 -o grab grab.f ~icore77 -Icore -Isunwindow -Ipbcrect -Im 

where grab./ is the FORTRAN source program. Note that /utrf libHtbcore,a must be linked 
with the program (the —leore option), and f utrfUbjHbeore77,a must come before it (the 
-leore77 option). 

Defined constants may be referenced in source programs by including 
/utrfineludeju$ereore77,h In a FORTRAN program, this must be done via a source statement 
like: 


include ’'/usr/include/usereore77.h” 

This include statement must be in each FORTRAN program unit which uses the defined con* 
stants, not just once in each source program file. The default primitive attribute structure PRI- 
MATTS which is provided in u»er€ore.h and is described in section 6.1.23 of this manual is not 
provided in u*ereore77.h because of FORTRAN’S restrictions on the ordering of specification 
statements and data statements. 

In the Sun release of FORTRAN-77, names are restricted to sixteen characters in length and may 
not contain the underline character. For this reason, FORTRAN programs must use abbreviated 
names to call the corresponding SunCore functions. The correspondence between the full 
SunCore names and the FORTRAN names appears later in this appendix. In addition, 
FORTRAN-77 declarations for all SunCore functions appear at the end of this appendix. 


C.l. Programming Tips 

• The abbreviated names of the SunCore functions are less readable than the full length 
names because the underfine character cannot be used in the FORTRAN names. However, 
since FORTRAN doesn’t distinguish between upper>case and lower-case letters in names, 
upper-case characters can be used to improve readability. There is an example of this later in 
this appendix. 

• Character strings passed from FORTRAN programs to SunCore cannot be longer than 256 
characters. 
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• FORTRAN passes ail arguments by reference. Although some SunCore functions receive 
arguments by value, the FORTRAN programmer need not worry about this. The interface 
routines in ju9rflih}Uhcore77»a handle this situation correctly. When in doubt, look at the 
FORTRAN declarations for SunCore functions at the end of this appendix. 

• SunCore uses pointers in some places. For instance, view surface structures contain pointers 
to device driver functions. Also, the ratttr data type includes a pointer to an array of 
short's containing the raster data. There are no pointer types In FORTRAN, but there are 
ways to handle all uses of pointers required to use SunCore. For view surface names, the 
following fragments of C code and FORTRAN code do the same thing: 


C Code 

FORTRAN Code 

struct vwsurf vsurf =» NULL_VWSURF; 

integer vsurf(VWSURFSIZE) 

ini bwldd(); 

integer bwldd 
external bwldd 

vsurf.dd ■- bwldd; 

data vsurf /VWSURFSIZE*0/ 
v8urf(DDINDEX) - loc(bwldd) 

initialize_viewjjurface(&vsurf, FALSE); 

call InitialiseVwsurf(vsurf, FALSE) 


The constants VWSURFSIZE and DDINDEX are defined in u»trcore77»h. The constant VWSURF- 
NEWFLO is also defined in uaereore77,h. See appendix B for more details on view surfaces. 

As shown above, all required pointer manipulation can be done with the FORTRAN loc library 
function, whick returns the address of its argument as an integer. 

SunCore function arguments which are pointers to structures can be declared as arrays in 
FORTRAN. For example, the C and FORTRAN declarations of the SunCore reefer structure 
are shown below: 


C Code 

FORTRAN Code 

struct { 

int width, height, depth; 
short *bits; 

integer raster(4) 

} raster; 



Then the following fragments of C and FORTRAN code are equivalent: 
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C Code 

FORTRAN Code 

short data[16]; 

integer*2 data(16) 

raster.width = 16; 

raster(l) = 16 

raster.height = 16; 

raster(2) == 16 

raster.depth = 1; 

raster(3) =» 1 

raater.bits = data; 

raster(4) = loc(data) 


• Some SunCore structures contain both int^s and float’s. For instance, the argument to 
inquirc_viemng_parametcra contains both int’s and float’s. This can be handled in FORTRAN 
by declaring a REAL array and an INTEGER surray which are made to share storage by an 
EQUIVALENCE statement. Then following the call to the inquiry function, the REAL com¬ 
ponents can be accessed by using the REAL array and the INTEGER components accessed 
via the INTEGER array. 

• Since FORTRAN does not distinguish between upper-ease and lower-case letters in identifiers, 
any FORTRAN program unit which includes the user cor e77.h header file cannot use identifiers 
with the same spelling as any constant defined in that header file (regardless of case). 

• The filetoraater and raaterto/Ue functions in C take an argument that is a UNIXf file descrip¬ 
tor. The corresponding argument to the FORTRAN functions is a logical unit number (LUN). 
This unit should be explicitly opened by using the FORTRAN open statement. I/O to the 
opened file should be done only via the filetoraater and raatertofUe functions. 

C.2. Example Program 

This example is the FORTRAN equivalent of the very simple program for drawing a martini 

glass. 


f UNIX Lb ft trftdemftrk of Bell Lftborfttories. 
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include " /usr/incIude/usercore77.h" 

integer v8urf(VWSURFSIZE) 
integer bwldd 
external bwldd 

integer InitializeCore, InitializeVwsurf, SelectVwsurf 
real glassdx(9), gla8sdy(9) 

data glassdx /-lO.0,9,0,0.0,-14.0,30.0-14.0,0.0,9.0,-10.0/ 
data glassdy /O.0,1.0,19.0,16.0,0.0,-15.0,-19.0,-1.0, 0.0/ 
data vsurf /VWSURFSIZE*0/ 

v5urf(DDINDEX) — loc(bwldd) 

if (InitiaUzeCorc(BASIC, NOINPUT, TWOD) .ne, 0) call exit(l) 

if (InitiaIizeVw8urf(vsurf, FALSE) .ne. 0) call exit(2) 

if (SelcctVwsuri^vsurf) .ne. 0) call exit(3) 

call SetViewport2(0.125, 0.876, 0.126, 0.75) 

call SetWindow(-50.0, 60.0, -10.0, 80.0) 

call CreateTempSeg() 

call MoveAbs2(0.0, 0.0) 

call PolylineRel2(gla3sdx, glassdy, 9) 

call MoveRel2(-12.0, 33.0) 

call LineRel2(24.0, 0.0) 

call CloseTempSeg() 

call 8leep(10) 

call DeselectVwsurf(vsurf) 
call TerminateCoreO 
end 


C-4 


Revision E of 7 January 1984 


SunCore Reference Manual 


Using SunCore with Fortrau-77 Programs 


C.3. Correspondence Between C Names and FORTRAN Names 


Correspondence Between C Names and FORTRAN Names 

Long Name 

FORTRAN Equivalent 

allocate_raster 
aw ait_any_button 
aw ait_any_button_get_loc ator_2 
aw ait_any_button_get_valuator 
aw ait_key board 

allocateraster 
awaitanybutton 
awtbuttongetloc 2 
awtbuttongetval 
aw aitkey board 

await^ick 

await_8troke_2 

begin_batch_of_update8 

Glo8e_jetained_8egment 

close^temporaryjiegment 

awaitpick 

awaitstroke2 

beginbatcbupdate 

closeretainseg 

closetempseg 

create_^etained_8egment 
createjtemporary_segment 
define_coIor_indice8 
delete_alljretained_8egments 
deletejretainedjsegment 

createretainseg 

createtempseg 

defcolorindices 

delallretainsegs 

delretainsegment 

de8elect_viewjjurface 

end_batch_of_update8 

file_to_ra8ter 

freejraster 

getjmousejstate 

deselectvw surf 

endbatchupdate 

filetoraster 

freeraster 

getmousestate 

getjaster 

initialisejcore 

initializejdevice 

initialize_yiewjiurface 

inquire_charju8t 

getraster 
initializecore 
initialized evice 
initialize vwsurf 
inqcharjust 

inquirej:narpath_2 

inquirejcnarpathJS 

inquirejcharprecision 

inquirejcharsize 

inquire.charspace 

inqcharpath2 

inqcharpathS 

inqcharprecision 

inqcharsize 

inqcharspace 

inquire_charup_2 

inquire_charup_3 

inquire_colorJndice8 

inquire_cnrrent_position_2 

inquire_current_position_3 

inqcharup2 

inqcharupS 

inqcolorindices 

inqcurrpos2 

inqcurrposS 

inquirejdetectabUity 

inquire.echo 

inqdetectability 

inqecho 
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Correspondence Between C Names and FORTRAN Names 

Long Name FORTRAN Equivalent 

inquire_echo_position 

inquire_echo_surface 

inquire_fill_index 

inqechoposition 

inqechosurface 

inqfillindex 

inquire_font 

inquire_highlighting 

inquire_im agejtr ansform ation_2 

inquire_image_transformation_3 

iEquire_image„transformation^type 

inqfont 

inqhighlighting 

inqimgtransform2 

inqimgtransform3 

inqimgxformtype 

inquire_im agejtranslate_2 

inquire_image_translate_3 

inquire_inverse_composite_matrbc 

inquire_keyboard 

inquire_line_index 

inqimgtranslate2 
inqimgtranslateS 
inqinvcom p m atrix 
inqkey board 
inqlineindex 

inquirejinestyfe 
inquirejinewidth 
inquireJlocator_2 
inquirejnarkerjsymbol 
inquire_ndc_sp ace_2 

inqlinestyle 

inqlinewidth 

inqlocator2 

inqmarkersymbol 

inqndcspace2 

inquire_ndcjsp ace_3 

inquire_openjrctainedjsegment 

inquire_open_tcnipo*‘3ry_segment 

inquire_j>en 

inquire_pickjd 

inqndcspace3 

inqopenretainseg 

inqopentempseg 

inqpen 

inqpickid 

inquire_polygon^edge_style 

inquirc_polygonJnterior_style 

inquire_primitive_attributes 

inquire_projection 

inquire_rasterop 

inqpolyedgestyle 

inqpolyintrstylc 

inqprimattribs 

inqprojection 

inqrasterop 

inquire_retained_segment_name5 
inquirejretained_segment_surfaces 
inquire jsegment_detect abi lity 
inquire_segment„highlighting 
inquire_3egment_image_transformation_2 

inqretainsegname 

inqretainsegsurf 

inqsegdetectable 

inqseghighlight 

inqsegimgxform2 

inquire_segment„.image_transformation_3 

inquire_segment_image_transformation_typc 

inquire_3egment_image_translate_2 
inquire_segm entjm age_tr anslateJS 
inquire_segment_visibility 

inqsegimgxfonn3 

inqsegimgxfrmtyp 

inqsegimgxlate2 

inq3egimgxlate3 

inqsegvisibility 
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Correspondence Between C Names and FORTRAN Names 

Long Name 

FORTRAN Equivalent 

inquire_8troke 

inqstroke 

inquire_text_extentJJ 

inqtextextent2 

inquire_text_extent_3 

inqtextextent3 

inquirejtextjndex 

inqtextindex 

inquire_valuator 

inqvaluator 

inquirc_view_depth 

inqviewdepth 

inquire_vicw_plane_di8tance 

inqviewplanedist 

inquire_yiew_plane_normal 

inqviewplanenorm 

inqiiirc_vicw_j*ferenccj>oint 

inqviewrefpoint 

inquire_vicw_upj2 

inqviewup2 

inquire_view_upj8 

inqviewupS 

inquire viewing control parameters 

inqvwgcntrlparms 

inquire viewing parameters 

inqviewingparams 

inquirejriewport_2 

inqviewport2 

inquirejriewportjS 

inqviewportS 

inquire^visibiliiy 

inqvisibility 

inquire.window 

inqwindow 

inquire_worldjBoordinate_matrixj2 

inqworldmatrix2 

inquire_wprldjcoordinate_ni atrixJ3 

inqworldmatrix3 

line_abs^i 

lineab82 

line^absjj 

lineabsS 

line_rel_2 

linerel2 

line_rel_3 

linerel3 

mapjttdcjto_world^2 

mapndctoworld2 

msp_jide_to_worldJ5 

mapndctow orldS 

map_worldJ;o^adc_2 

mapworldtondc2 

map_‘world_tojidcj3 

mapworldtondc3 

marker_absJ2 

markerab82 

marker_absJ3 

markerabsS 

markerjreL2 

markerrel2 

marker_jel_3 

markerrelS 

move_ab8_^ 

moveabs2 

move_abs_3 

moveabs3 

move_reL2 

moverel2 

movejreljS 

moverelS 

newjTrame 

newframe 

poIygon_jsbs_2 

polygonabs2 

polygon_abs_3 

polygonabsS 

polygon_jeL2 

polygonrel2 


Revision E of ? January 1984 


C-? 





Using SunCore with Fortran-77 Programs 


SunCore Reference Manual 


Correspondence Between C Names and FORTRAN Names 


Long Name FORTRAN Equivalent 


polygon„rel_3 

polygonrel3 

polyline_abs_2 
polyline_absj3 
polyline_rel_2 
polylinejreIJS 
poly m arker_abB_2 

polylineab$2 

polylineabsS 

polylinerel2 

polylinerel3 

polymarkeTab82 

polymarker_ab8j3 

polymarkerjrelJJ 

polymarker_yel_3 

print_erTor 

putjaster 

polym arker abs3 
polymarkerrel2 
polym arkerrel3 
printerror 
putraster 

rasterjbo_file 
rename_retained_segment 
report_mo8tjrcccnt_error 
restorejsegment 

8ave_8egment 

rastertofile 

renameretainseg 

reportrecenterr 

restoresegment 

savesegment 

select_viewj5urf ace 
8et_back_pianejclipping 

8Ct_ch»jU8t 

set_charpath_2 

setjcharpathjS 

selectvwsurf 

setbackclip 

setcharjust 

setcharpath2 

8etcharpath3 

setjcharprecision 

5et_char8ize 

setjcharspace 

8etjcharup_2 

8et_charup_3 

8etcharprecisiott 

setchausize 

setcharspace 

8etcharttp2 

setcharupS 

8et_coordinate_sy8tcm_type 

set_detectability 

set_drag 

setjecho 

setjecho_group 

8etcoord8ystype 

setdetectability 

setdrag 

setecho 

setechogroup 

set_echo_position 

8et_echo_surface 

8et_filUndex 

set_font 

set_front_plane_clipping 

setechoposition 

setechosurface 

setfillindex 

setfont 

setfrontclip 

set_highlighting 

8et_image_transformation_2 

sethighlighting 

setimgtransform2 
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Correspondence Between C Names and FORTRAN Names 

Long Name 

FORTRAN Equivalent 

8et_image_transformationJ3 

8etJmage_transformationjtype 

8etJmagejtranslate_2 

setimgtransformS 

setimgxformtype 

setimgtranslate2 

8etjmage_tran8late_3 

setjceyboard 

8et_lightjdirection 

8et_line_index 

8et_line8tyle 

setimgtranslateS 

setkeyboard 

setlightdirect 

setlineindex 

setlinestyle 

8et_Iinewidth 

8etJocator_2 

setjnarkerjuymbol 

8et_ndc_8pace_2 

setjidc_8pace_3 

setlinewidth 

set!ocator2 

setmarkersymbol 

8etndcspace2 

setndcspaceS 

8et_output_clipping 

8et_pen 

8et_pickjd 

8etj)olygon_edgejstyIe 

8etj)olygonJnteriorjstyle 

setoutputclip 

setpen 

setpickid 

setpolyedgestyle 

setpolyintrstyle 

8et_primitiTe_attribute8 

8et_projeetion 

8etjra8terop 

setjiegmentjdeteetability 

setjsegment.highlighting 

setprimattribs 

setprojection 

setrasterop 

setsegdetectable 

setseghighlight 

8et_8egment_imagejtransformation_2 

8et_8egmentJmage_tran8formation_3 

8et_8egmentJmagejtran8late_2 

8eOegmentJmagejtran8late_3 

setjsegmentjvisibility 

setsegimgxform2 

setsegimgxformS 

8etsegimgxlate2 

setsegimgxlateS 

setsegvisibility 

set shading parameters 
setjstroke 
setjtextjndex 
setjyaluator " 
setjvertexjndices 

setshadingparams 
setstroke 
settextindex 
setvaluator 
set vertex indices 

set_vertex_normal3 

8et_Tiew_depth 

8ct_view_planejdistance 

8et_view_j>Iane_normal 

8et_view_reference_point 

set vertex norm als 

setviewdepth 

setviewplanedist 

setviewplanenorm 

setviewrefpoint 
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Correspondence Between C Names and FORTRAN Names 

Long Name 

FORTRAN Equivalent 

set_view„up_2 

set view up2 

set_view_up_3 

setviewupS 

5et_viewing_parameter8 

setviewittgparams 

8etjviewport_2 

8etviewport2 

8et_viewport_3 

setviewportS 

setjvisibility 

setvisibility 

8et_window 

setwindow 

set^window_clipping 

setwindowelip 

5et_world_coordinate_jnatrix_2 

setworldmatrix2 

8et_world_coordinate_matrix_3 

setworldmatrix3 

8et_zbuffer_cut 

setzbuffercut 

siaejraster 

sizeraster 

terminate_core 

terminatecore 

terminate^device 

terminatedevice 

terminate_view_8urface 

terminatevwsurf 

text 

text 


C.4. FORTRAN Interfaces to SunCore 

Note: Although all SunCore proeeduret are declared here a» funetiono, each may edto be tidied at 
a subroutine if the user does not want to cheek the returned value. 

integer function aIlocatera8ter(raster) 
integer ra8ter(4) 

integer function awaitanybutton(time, buttonnum) 
integer time, buttonnum 

integer function awtbuttongetloe2(time, locatomum, buttonnum, x, j) 
integer time, locatornum, buttonnum 
real x, y 

integer function awtbuttongetval(time,valuatornum,buttonnum,value) 
integer time, valuatornum, buttonnum 
real value 

integer function awaitkeyboard(time, keyboardnum, inputstring, length) 
integer time, keyboardnum 
character*(*) inputstring 
integer length 
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integer function awaitpick(time, picknum, segname, pickid) 
integer time, picknum, segname, pickid 

integer function awaitstroke2(time, strokenum, arraysize, xarray, yarray, n) 
integer time, strokenum, arraysize 
real xarray, yarray 
integer n 

integer function beginbatchupdate() 

integer function cIoseretainseg() 

integer function closetempseg() 

integer function createretainseg(segname) 
integer segname 

integer function createtempsegO 

integer function defcolorindices(8urfacename, il, 12, red, green, blue) 
integer surfacename( *) 
integer il, i2 

real red(*), green(*), blue(*) 

integer function delallretainsegsO 

integer function delretain8egment(segname) 
integer segname 

integer function deselectvwsurf(surfacename) 
integer surfacename( *) 

integer function endbatchupdate() 

integer function fiIetora3ter(rasfid, raster, map) 
integer rasfid 
integer raster(4) 
integer map(3) 

integer fxmction freeraster(raster) 
integer raster(4) 
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integer function getmousestate(x, y, buttons) 
real x, y 
integer buttons 

integer function getraster(surfacenanie, xmin, xmax, ymin, ymax, xd, yd, raster) 

integer surfacename( *) 

real xmin, xmax, ymin, ymax 

integer xd, yd 

integer raster(4) 

integer function initializecore(outputleTel, inputlevel, dimension) 
integer outputlevel, inputlevel, dimension 

integer function initializedevice(deviceclass, devicenum) 
integer deviceclass, devicenum 

integer function initializevwsurf(surfacename, tsrpe) 
integer 8urfacename( *) 
integer type 

integer function inqcbarjust(ju8t) 
integer just 

integer function inqcbarpath2(dx, dy) 
real dx, dy 

integer function inqcharpath3(dx, dy, dz) 
real dx, dy, dz 

integer function inqcharprecision(charprecision) 
integer charprecision 

integer function inqcbarsize^charwidth, cbarheight) 
real charvidtb, char height 

integer function inqcharspace(charspace) 
real charspace 

integer function inqcharup2(dx, dy) 
real dx, dy 

integer function inqcharup3(dx, dy, dz) 
real dx, dy, dz 
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integer function inqcolorindices(surfacename, il, i2, red, green, blue) 
integer surfacename( *) 
integer il, i2 

real red(*), green(*), blue(*) 

integer function inqcurrpos2(x, y) 
real x, y 

integer function inqcurrpos3(x, y, z) 
real x, y, z 

integer function inqdetectability(detectability) 
integer detectability 

integer function inqecho(deyiceclas8, devicenum, echotype) 
integer deviceclass, devicenum, echotype 

integer function inqechoposition(deviceclas8, devicenum, echox, echoy) 
integer deviceclass, devicenum 
real echox, echoy 

integer function inqecho8urface(devicecla8S, devicenum, surfacename) 
integer deviceclass, devicenum 
integer 8urfacename(*) 

integer function inqfillindex(index) 
integer index 

integer function inqfont(font) 
integer font 

integer function inqhighlighting(highlighting) 
integer highlighting 

integer function ittqimgtransform2(sx, sy, a, tx, ty) 
real sx, sy, a, tx, ty 

integer function inqimgtransform3(sx, sy, sz, ax, ay, az, tx, ty, tz) 
real sx, sy, sz, ax, ay, az, tx, ty, tz 

integer function inqimgxformtype(type) 
integer type 

integer function inqimgtranslate2(tx, ty) 
real tx, ty 
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integer function inqimgtranslate3(tx, ty, tz) 
real tx, ty, tz 

integer function inqinvcompmatrix(array) 
real array(4,4) 


integer function inqkeyboard(keyboardnum, buffersize, initstring, initcursor) 
integer keyboardnum, buffersize 
character*(*) initstring 
integer initcursor 

integer function inqlineindex(index) 
integer index 

integer function inqlinestyle(line8tyle) 
integer linestyle 

integer function inqlinewidth(Iine'width) 
real linewidth 

integer function inqlocator2(locatomum, x, y) 
integer locatornum 
real x, y 

integer function inqmarkersymbol(symbol) 
integer symbol 

integer function inqndcspace2('width, height) 
real width, height 

integer function inqndc3pace3(width, height, depth) 
real width, height, depth 

integer function inqopenretainseg(segname) 
integer segname 

integer function inqopentempseg(open) 
integer open 

integer function inqpen(pen) 
integer pen 

integer function inqpickid(pickid) 
integer pickid 
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integer function inqpolyedgestyle( style) 
integer style 

integer function inqpolyintrstyle(8tyle) 
integer style 

integer function inqprimattribs(primattr) 
integer primattr(28) 

Note: The actual argument in the calling program corresponding to primattr should be an array 
which can be referenced both as a real array and as an integer array in order to access both 
integer valued and real valued primitive attributes. This can be done using the equivalence state¬ 
ment, 

integer function inqprojection(projection, dxproj, dyproj, dzproj) 

integer projection 

real dxproj, dyproj, dzproj 

integer function inqra8terop(rop) 
integer rop 

integer function inqretainsegname(arraysize, namearray, numberofsegments) 
integer arraysize, namearray(*), numberofsegments 

integer function inqretainsegsurf(8egname, arraysize, vwsurfarray, numsurf) 
integer segname, arraysize 
integer vwsurfarray(*) 
integer numsurf 

Note: arraysize should give the number of view surface structures which can be held in vwsurfar- 
ray. Each structure requires VWSURFSIZE elements of vwsurf array. 

integer function inqsegdetectable(8egname, detectability) 
integer segname, detectability 

integer function ittqseghighlight(segname, highlighting) 
integer segname, highlighting 

integer function inqsegimgxform2(segname, sx, sy, a, tx, ty) 
integer segname 
real sx, sy, a, tx, ty 

integer function inqsegimgxform3(segname, sx, sy, sz, ax, ay, az, tx, ty, tz) 
integer segname 

real sx, sy, sz, ax, ay, az, tx, ty, tz 

integer function inqsegimgxfrmtyp(segname, type) 
integer segname, type 
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integer function inqse^mgxlate2(segname, tx, ty) 
integer segname 
real tx, ty 

integer function inqsegimgxlate3(segname, tx, ty, tz) 
integer segname 
real tx, ty, tz 

integer function inqsegvisibility{segname, visibility) 
integer segname, visibility 

integer function inqstroke(strokenum, bufsize, dist, time) 
integer strokenum, bufsize 
real dist 
integer time 

integer function inqtextextent2(string, dx, dy) 
character*(*) string 
real dx, dy 

integer function inqtextextent3(string, dx, dy, dz) 
character*(*) string 
real dx, dy, dz 

integer function inqtextindex(index) 
integer index 

integer function inqvaluator(valuatornum, initialvalue, low, high) 
integer valuatornum 
real initialvalue, low, high 

integer function inqviewdepth(frontdi8tance, backdistance) 
real frontdistance, backdistance 

integer function inqviewplanedist(viewdistance) 
real view distance 

integer function inqviewplanenorm(dxnorm, dynorm, dznorm) 
real dxnorm, dynorm, dznorm 

integer function inqviewrefpoint(x, y, z) 
real x, y, z 

integer function inqviewup2(dxup, dyup) 
real dxup, dyup 
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integer function inqTiewup3(dxup, dyup, dsup) 
real dxup, dyup, dsup 

integer function inqvi?gcntrlpums(i?indo'wclip, frontclip, backclip, type) 
integer windowclip, frontclip, backclip, type 

integer function inqYiewingparams(Tiewparam8) 
real Tie'wparams(26) 

Note: The actuat argument in the calling program correeponding to viewparams should be an 
array which can be referenced both as a real array and as an integer array in order to access both 
integer valued and real valued viewing parameters. This can be done using the equivalence state¬ 
ment. 


integer function inqviewport2(xmin, xmax, ymin, ymax) 
real xmin, xmax, ymin, ymax 

integer function inqTie'wport3(xmin, xmax, ymin, ymax, smin, rmax) 
real xmin, xmax, ymin, ymax, zmin, zmax 

integer function inqvisibility(vl8ibility) 
integer vieibility 

integer function inq«indow(umin, umax, vmin, vmax) 
real umin, umax, vmin, vmax 

integer function inqvorldmatrix2(array) 
real array(3,3) 

integer function inqworldmatrix3(array) 
real array(4,4) 

integer function lineab82(x, y) 
real x, y 

integer function !ineabs3(x, y, s) 
real x, y, t 

integer function Iinerel2(dx, dy) 
real dx, dy 

integer function lmerei8(dx, dy, dz) 
real dx, dy, dz 

integer function mapndctoworld2(ndcx, ndcy, wldx, widy) 
real ndcx, ndcy, wldx, wldy 
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integer function mapndcto'world3(ndcx, ndcy, ndcz, wldx, wldy, wldz) 
real ndcx, ndcy, ndcz, wldx, wldy, wldz 

integer function mapworldtondc2(wldx, wldy, ndcx, ndcy) 
real wldx, wldy, ndcx, ndcy 

integer function mapworldtondc3(wldx, wldy, wldz, ndcx, ndcy, ndcz) 
real wldx, wldy, wldz, ndcx, ndcy, ndcz 

integer function markerab82(x, y) 
real x, y 

integer function markerab53(x, y, z) 
real x, y, z 

integer function markerrcl2(dx, dy) 
real dx, dy 

integer function markerrel3{dx, dy, dz) 
real dx, dy, dz 

integer function moYeab82(x, y) 
real x, y 

integer function moveabs3(x, y, z) 
real x, y, z 

integer function moverel2(dx, dy) 
real dx, dy 

integer function moverel3(dx, dy, dz) 
real dx, dy; dz 

integer function newframe() 

integer function polygonabs2(xarray, yairay, n) 
real xarray(*), yarray(*) 
integer n 

integer function polygonabs3(xarray, yarray, zarray, n) 
real xarray(*), yarray(*), zarray(*) 
integer n 

integer function polygonrel2(dxarray, dyarray, n) 
real dxarTay(*), dyarray(*) 
integer n 
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integer function polygonreI3(dxarray, dyarray, dzarray, n) 
real dxarray(*), dyarray(*), dzarray(*) 
integer n 

integer function poIylineabs2(xarray, yarray, n) 
real xarray(*), yarray(*) 
integer n 

integer function poIylineabs3(xarray, yarray, zarray, n) 
real xarray(*), yarray(*), zarray(<*) 
integer n 

integer function polyUnerel2(dxarray, dyarray, n) 
real dxarray(*), dyarray(*) 
integer n 

integer function polylinerel3(dxarray, dyarray, dzarray, n) 
real dxarray(*), dyarray(*), dzarray(*) 

Integer n 

integer function poiymarkerab82(xarray, yarray, n) 
real xarray(*), yaiTay(*) 
integer n 

integer function polyniarkerab83(xarray, yarray, zarray, n) 
real XMray(*), yarray(*), zarray(*) 
integer n 

integer function polyniarkerrel2(dxarray, dymay, n) 
real dxarray(*), dyarray(*) 
integer n 

integer function polymarkerrel3(dxarray, dyarray, dzarray, n) 
real dxarray(*), dyarray(*), dzarray(*) 
integer n 

integer function printerror(mes8age, erromum) 
character*(*) me88age 
integer erromum 

integer function putra8tei(raster) 
integer raster(4) 


Revision E of 7 January 1984 


C-19 




Using SunCore with Fortran-77 Programs 


SunCore Reference Manual 


integer function rastertofile(raster, map, rasfid, n) 
integer raster(4) 
integer map(3) 
integer rasfid, n 

integer function renameretain8eg(8egname, newname) 
integer segname, newname 

integer function reportrecenterr(errornum) 
integer erromum 

integer function restoresegment(segname, filename) 
integer segname 
character*(*) filename 

integer function 8avesegment(segname, filename) 
integer segname 
character'*'('*) filename 

integer function 5electvwsurf(surfacename) 
integer surfacename( *) 

integer function setbackc!ip(onoff) 
integer onoff 

integer function setcharjustQust) 
integer just 

integer function aetcharpath2(dx, dy) 
real dx, dy 

integer function 8etcharpath3(dx, dy, dz) 
real dx, dy, dz 

integer function setcharprecision(charprecision) 
integer charprecision 

integer function setcharsize(charwidth, charheight) 
real charwidth, charheight 

integer function setcharspace(charspace) 
real charspace 

integer function setcharup2(dx, dy) 
real dx, dy 
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integer function setcharup3(dx, dy, dz) 
real dx, dy, dz 

integer function Betcoordsy8type(type) 
integer type 

integer function 8etdetectability(detectability) 
integer detectability 

integer function 8etdrag(mode) 
integer mode 

integer function setecho(deviceclass, devicenum, echotype) 
integer deviceclass, devicenum, echotype 

integer function setechogroup(deyiceclass, devicenumarray, n, echotype) 
integer deviceclass, devicenumarray(*), n, echotype 

integer function setechoposition(deTiceclass, devicenum, echox, echoy) 
integer deviceclass, devicenum 
real echox, echoy 

integer function setechosurface(devicecla88, devicenum, surfacename) 
integer deviceclass, devicenum 
integer 8urfacename( ) 

integer function 8etfillindex(index) 
integer index 

integer function 8etfont(font) 
integer font 

integer function setfrontclip(ono£r) 
integer onoff 

integer function 8ethighlighting(highlighting) 
integer highlighting 

integer function 8etimgtransform2(sx, sy, a, tx, ty) 
real sx, sy, a, tx, ty 

integer function setimgtransform3(sx, sy, sz, ax, ay, az, tx, ty, tz) 
real sx, sy, sz, ax, ay, az, tx, ty, tz 

integer function setimgxformtype(type) 
integer type 
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integer function 8et;mgtranslate2(tx, ty) 
real tx, ty 

integer function setimgtranslate3(tx, ty^ tz) 
real tx, ty, tz 

integer function 8etkeyboar<l(keyboardnum, buffersize, initstring, initcursor) 
integer keyboardnum, buffersize 
character*(*) initstring 
integer initcursor 

integer function 8etlightdirect(dx, dy, dz) 
real dx, dy, dz 

integer function setlineindex(index) 
integer index 

integer function 8etlinestyle(linestyle) 
integer linestyle 

integer function setHnewidth(linewidth) 
real linewidtli 

integer function 8etlocator2(locatomum, x, y) 
integer locatornum 
real x, y 

integer function setmarker8ymbol(8ymbol) 
integer symbol 

integer function setndcspace2(width, height) 
real Tridth, height 

integer function 8etndcspace3(width, height, depth) 
real u'idth, height, depth 

integer function 8etoutputclip(onoff) 
integer onoff 

integer function setpen(pen) 
integer pen 

integer function setpickid(pickid) 
integer pickid 
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integer function 8ctpolyedgestyle(8tyle) 
integer style 

integer function setpolyintrstyle($tyIe) 
integer style 

integer function setprimattribs(primattr) 
integer primattr(28) 

Note: The oetual argument in the calling program eorreeponJing to primattr should be an array 
which can be referenced both as a real array and as an integer array in order to access both 
integer vedued and reof valued primitive attributes. This can be done using the equivalence state¬ 
ment. 

integer function setprojection(projection, dxproj, dyproj, dzproj) 

integer projection 

real dxproj, dyproj, dzproj 

integer function 8etra8terop(rop) 
integer rop 

integer function 8et8egdetectable(8egnanie, detectability) 
integer segname, detectability 

integer function 8et8eghighlight(8egname, highlighting) 
integer segname, highlighting 

integer function 8et8egimgxfonn2(segna]ne, sx, sy, a, tx, ty) 
integer segname 
real sx, sy, a, tx, ty 

integer function 8et8egimgxform3(segname, sx, sy, sz, ax, ay, az, tx, ty, tz) 
integer segname 

real sx, sy, sz, ax, ay, az, tx, ty, tz 

integer function 8et8egimgxlate2(8egname, tx, ty) 
integer segname 
real tx, ty 

integer function 8et8egimgxlate3(8egname, tx, ty, tz) 
integer segname 
real tx, ty, tz 

integer function setsegvisibility(segname, visibility) 
integer segname, visibility 
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integer function 8etshadingparams(ambient, diffuse, specular, flood, bump, hue, style) 
real ambient, diffuse, specular, flood, bump 
integer hue, style 

integer function 8etstroke(strokenum, buffersize, distance, time) 
integer strokenum, buffersize 
real distance 
integer time 

integer function settextindex(index) 
integer index 

integer function setvaluator(Taluatornam, initialyalue, low, high) 
integer valuatornum 
real initialvalue, lo-w, high 

integer function setyertexindices(colorindexIist, n) 
integer colorindexli8t(i'), n 

integer function setyertexnorma]8(xlist, ylist, zlist, n) 
real xli8t(*), yli8t(*), zlist(*) 
integer n 

integer function 8etviewdepth(frontdi8tance, baekdistance) 
real frontdistance, baekdistance 

integer function 8etyie'wplanedist(di8tance) 
real distance 

integer function setyie'wplanenorm(dxnorm, dynorm, dznorm) 
real dxnorm, dynorm, dznorm 

integer function 8etyiewrefpoint(x, y,») 
real x, y, z 

integer function 8ctyiewup2(dx, dy) 
real dx, dy 

integer function setviewup3(dx, dy, dz) 
real dx, dy, dz 

integer function setyiewingparams(yiewparam8) 
real viewparams(26) 

Note: The actual argument in the calling program corresponding to viewparams should be an 
array which can be referenced both as a real array and as an integer array in order to access both 
integer valued and real valued viewing parameters. This can be done using the equivalence 
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statement. 

integer function setviewport2(xmin, xmax, ymin, ymax) 
real xmin, xmax, ymin, ymax 

integer function setviewport3{xmin, xmax, ymin, ymax, zmin, zmax) 
real xmin, xmax, ymin, ymax, zmin, zmax 

integer function setvisibility(visibility) 
integer visibility 

integer function setwindow(umin, umax, vmin, vmax) 
real umin, umax, vmin, vmax 

integer function 8etwindowclip(onofl) 
integer onoff 

integer function 8etworldmatrix2( array) 
real array{3,3) 

integer function 8etworIdmatrix3{array) 
real array(4,4) 

integer function setzbuffercut(surfacename, xlist, zlist, n) 
integer 8urfacename(*) 
real xlist(*), zli8t(*) 
integer n 

integer function sizera 3 ter( 8 urfacename, xmin, xmax, ymin, ymax, raster) 

integer surfacename{ * ) 

real xmin, xmax, ymin, ymax 

integer ra8ter(4) 

integer function terminatecore() 

integer function terminatedevice{deviceclass, devicenum) 
integer deviceelass, devicenum 

integer function terminatevwsurf(surfacename) 
integer surfacename( ) 

integer function text(8tring) 
character*(*) string 
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Appendix D 


Using SunCore with Pascal Programs 


All functions provided in SunCore may be called from Pascal programs by linking them with 
the /uer/tibjlibcoreptu,0 library by using the Pascal compiler with a command line of the form: 

% pc —o grab grab.p —Icorepas —icore —Isunwindow —Ipixrect —Im 

where grab.p is the Pascal source program. Note that fmrflibflibcore.a must be linked with 
the program (the —Icore option), and /utrUibfiibcorepas.a must come before it (the —Icorepas 
option). 


D.l» Programming Requirements 

The files typedefspat.h, nacrcorepat.h, devincpas.h and sunpat.h from the 
f uarf include/pascal directory must be included in the user’s source code to provide the neces¬ 
sary declarations for the Pascal interface to SunCore. Pascal programs which call SunCore 
functions must place these include files in the most global declaration section of the program: 

program example (input,output) 

#include Vusr/mclude/pascal/typedcfspas.h* 

^include */usr/include/pascal/usercorepas^h’ 

var 

{user declarations} 

#include */u»r/include/pa8cal/devincpas.h’ 

#include ’/usr/include/paacal/sunpas.h’ 

If the Pascal program is composed of separately compiled files, these include statements must be 
in each Pascal file which uses SunCore functions and the corresponding defined constants. 
Defined constants for SunCore (see section on Useful Constants in the introduction to this 
manual) are set in the file /usr/include/pascal/usercorepas.h. The default primitive attribute 
structure PRIMATTS provided in usercore.h and described in the section describing 
set_primitive_attributes is not provided in usercorepas.h. 

The Sun release of Pascal does not support the passing of variable length arrays as arguments 
in function or procedure calls. Therefore, fixed length arrays which are compatible with the 
SunCore-Pascal interface are declared as predefined types in the typedefspas.k file (see the 
Declarations section of this appendix). The length of these arrays in 256. The length of char¬ 
acter strings passed from Pascal programs to SunCore must also be 256 characters. 

In the Sun release of Pascal, function names may not contain the underline character (_). There¬ 
fore, Pascal programs use abbreviated names to call the corresponding SunCore functions. 
The correspondence between the full SunCore names and the Pascal names appears in the 
Function Peclarations section of this appendix. To provide a mechanism for returning the 
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status of calls to SunCore routines, all SunCore routines must be called as functions from 
Pascal. Finally, although most SunCore functions use floats (32-bit reals), Pascal uses 64-bit 
reals. However, the Pascal programmer is only required to provide reals. SunCore functions 
which have structures as their arguments have corresponding predefined types in Pascal (see 
the Type Declarations section of this appendix). 

D.2. Limitations of SunCore-Pascal Interface 

In addition to the requirements of calling SunCore routines as functions and using fixed length 
character strings and arrays, two types of SunCore functions cannot be used in their standard 
forms because Pascal provides a less flexible mechanism for using pointers than C. In particu¬ 
lar Pascal does not support the use of pointers within structures. The two types of routines 
which accordingly require special treatment by the Pascal programmer are 

1. routines using view surface names 

2. routines concerning rasters and colormaps. 

D.2.1. Routines Using View Surface Names 

View surface names in SunCore are structures containing pointers to device driver routines. 
The device driver names are supplied by the include file devinepas.h. The user may then simply 
use one of these names: 

bwldd for the Sun-1 monochrome display, 

bw2dd for the Sun-2 monochrome display, 

cgldd for the color monitor 

pixwindd for windows on the Sun-1 monochrome display, 

cgpixwindd for windows on the color monitor. 

However, the device driver names must be inserted in the view surface structure. The pasloc 
function (provided in the SunCore-Pascal interface) transforms the function correspon^ng to 
the device driver into an integer which can then be inserted in the appropriate place in the dev¬ 
ice driver structure (see following example). 
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C Code 

Pascal Code 

struct vwsurf dsurf = NULL_VWSURF; 

var 

int bwldd(); 

dsurf :vwsurf; 

• 

tstr:vwsurfst; 

• 

tstr 

dsurf.dd =» bwldd; 

dsurf.dd pasloc(bwldd); 

dsurf.screenname := tstr; 
dsurf.windowname := tstr; 
dsurf.windowfd := 0; 
dsurf.instance := 0; 
dsurf.cmapsize :=> 0; 
dsurf.cmapname := tstr; 
dsurf.flags := 0; 
dsurf.ptr ;= 0; 

initialize_viewjsurface(&dsurf, FALSE); 

X := InitializeVw8urf(dsurf, FALSE); 


Assigning a literal string of two spaces (blanks) to the t$tr yariable will initialize the character 
array to all spaces. 


D.2.2. Routines Using Rasters and Colormaps 

For uses of SunCore functions which have rasters or colormaps as arguments which do not 
involve arithmetic direct manipulation by the programmer (e.g., writing a raster to a file), the 
following restrictions on the functions do not apply and the programmer is only required to call 
the function. SunCore raster and colormap structures contain pointers to variable length data 
(that is, dynamic arrays). The SunCore-Pascal interface declares these varaibles as integers. 

Pascal programmers wishing to alter the contents of the colormap or raster data within a pro¬ 
gram must write a C function which uses the pointer value returned in Pascal to copy the 
information into a fixed-length array. Arithmetic operations can then be performed on the data 
using conventional Pascal statements. The programmer must then write another C function to 
copy the information back into the array pointed to by the pointer returned by the SunCore- 
PasezJ interface. These C functions are not provided because the size of the fixed-length array 
will vary greatly among different applications. Therefore, the individual Pascal programmer 
must decide bow large an array to declare for each application. 


D.3, Example Program 

The use of the SunCopo-Pascal interface is illustrated by showing the text of a program for 
drawing the martini glass used in previous tutorial examples. 

program martiniglass (input,output); 

^include ’/usr/include/pascal/usercorepas.h’; 

^include 7uW>®cJ’^^®/P^®®‘V^yP®defs.h*; 
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yar 

glassdx, glassdy: parr {type parr is an array of reals of 
length 256 declared in typedefs.h}; 

xnnteger; 

dsurf:vwsurf; 

tstrrvwsurfst; 

function sleep(x:integer):integer; external; 

^include ’/usr/inchide/pascal/sunpas.h’; 

^include ’/usr/include/pascal/devincpas.h’; 

procedure loaddata; 
begin 

glassdxfl] := -10.0; glassdy[l] 0.0; 
glassdxl2j := 9.0; glassdyl2] := 1.0; 
glassdx [3] := 0.0; glassdy[sj := 19.0; 

glassdx[4j := -14.0; gla8sdy[4) := 15.0; 
glassdxfsj :=> 30.0; glassdy[5] := 0.0; 
glassdxje] :==3 -14.0; glassdy[6] := -15.0; 
glassdxj?] := 0.0; glassdy(7] := -19.0; 
glassdx [8] := 9.0; glassdy[8] := -1.0; 

glassdx[9] -10.0; glassdy[9] := 0.0; 

end; 

begin (main program} 
tstr := ’ ’; 

dsurf.screenname := tstr; 
dsurf.windowname := tstr; 
dsurf.windowfd 0; 
dsurf.dd :** pasloc(bwldd); 
dsurf.instance 0; 
dsurf.cmapsize 0; 
dsurf.cmapname tstr; 
dsurf.flags :»=“ 0; 
dsurf.ptr := 0; 

if (initializecore(BASIC, NOINPUT, TWOD) <> 0) then 
writeln (* error 1’) 
else 

if (initializevwsurf(dsurf, FALSE) <> 0) then 
writeln (* error 2’) 
else 

if (selectvwsurf(dsurf) <> 0) then 
writeln (’ error 3’) 
else 

X := setviewport2(0.125, 0.875, 0.125, 0.75); 
x setwindow(-50.0, 50.0, -10.0, 80.0); 

X := createtempseg; 

X := moveabs2(0.0, 0.0); 
loaddata; 

X polylinerel2(glassdx, glassdy,9); 
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end. 


X :=» moverel2{-12.0, 33.0); 
X := lmerel2(24.0, 0.0); 

X :=^ closetempseg; 

X :«= sleep(10); 

X :=» deselectvwsurf(d8urf); 
X :*=* tenninatecore; 
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0.4* Correspondence Between C Names and Pascal Names 


Correspondence Between C Names and Pascal Names 

SunCore Name Pascal Equivalent 

alloc ate_raster 
aw ait_any_button 
aw ait any button eet loc ator_2 
aw ait any button get_valuator 
aw ait_keyboard 

allocater aster 
aw aitany button 
awtbuttongetloc2 
awtbuttongetval 
aw ait key board 

await_pick 
aw ait jstroke_2 
begin_batch_of_updates 
close_jetained_segment 

clo5e_tenipor3^J*®S®i®Ji^ 

awaitpick 

await8troke2 

beginbatchupdate 

closeretainseg 

closetempseg 

create_retained_segment 
create_temporary_segment 
define_color_indices 
deletejalljretainedjsegme nts 
delete_retained_segment 

createretainseg 

createtempseg 

defcolorindices 

delallretainsegs 

delretainsegment 

deselect_view_surface 

end_batch_of_updates 

file_to_raster 

free_raster 

get_mouse_state 

deselectvwsurf 

endbatchupdate 

filetoraster 

freeraster 

getmousestate 

get_raster 

initialize_core 

initialize_device 

initi ali ze_view jsurface 

inquire_charjust 

getraster 

initializecore 

initializedevice 

initializevwsurf 

inqcharjust 

inquire_c h arpath_2 

inquire_charpath_3 

inquire_charprecision 

inquire^charsize 

inquire_charspace 

inqcharpath2 

inqcharpath3 

inqcharprecision 

inqcharsize 

inqcharspace 

inquire_charup_2 
inquire_charup_3 
inquire_color_indices 
inquire_current_position_2 
inquire_current_posit ion_3 

inqcharup2 

inqcharupS 

inqcolorindices 

inqcurrpos2 

inqcurrposS 

inquire_detectability 

inquire_echo 

inqdetectability 

inqecho 
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Correspondence Between C Names and Pascal Names 

SunCore Name 

Pascal Equivalent 

inquirejBcho_position 

inqechoposition 

inquire_eclio_8urface 

inqechosurface 

inquireJElllJndex 

inqfillindex 

inquire_font 

inqfont 

inquire_highlighting 

inqhighligkting 

inquire_im agejtransform ation_2 

inqimgtransform2 

inquirejm agejtransform ationjS 

inqimgtransform3 

inquireJmagejtransformation^srpe 

inqimgxformtype 

inquireJm agejbr anslate_2 

inqimgtranslate2 

inquireJmagejtranslatejS 

inqimgtran8late3 

inquireJnverse.compositejmatrix 

inqinvcompmatrix 

inquire_keyboard 

inqkey board 

inquireJineJndex 

inqlineindex 

inquirejinestyle 

inqlinestyle 

inquirejinewidth 

inqlinewidth 

inquire Joe ator_? 

inqlocator2 

inquire_piarkerjsymboI 

inqm arkersy m bol 

inquire^dc_8pace_2 

inqndc8pace2 

inquire_ndc_5pacc_3 

inqndcspaceS 

inquirejopenjretainedjsegment 

inqopenretainseg 

inquire_open_temporaryjsegment 

inqopentempseg 

inquire_pen ^. 

inqpen 

inquirejpickjd 

inqpickid 

inquire_polygon_edge_style 

inqpolyedgestyle 

inquirc_polygonJnterior_8tyle 

inqpolyintrstyle 

inquire_primitiTe_attributes 

inqprimattribs 

inquire_projection 

inqprojection 

inquirejrasterop 

inqrasterop 

inqttirejretainedjsegment_names 

inqretainsegname 

inquirej'etainedjsegmentjsurf aces 

inqret ainsegsurf 

inquirej!egment_detectability 

inqsegdetectable 

inquirejsegment_highlighting 

inqseghighlight 

inquirejiegmentJmageJran8formation_2 

inqsegimgxform2 

inquirejjegment Jm ageJransform ationjS 

inqsegimgxformS 

inquire_segmentJmage_transformation_type 

iuqsegimgxfrmtyp 

inquirejsegmentJm age_tr ansi ate_2 

inqsegimgxlate2 

inquire_8egmentjmage_translate_3 

inqsegimgxlate3 

inquirejsegment^visibility 

inqsegvisibility 
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Correspondence Between C Names and Pascal Names 

SunCore Name 

Pascal Elquivalent 

inquire_8trofce 

inqstroke 

inquire text_extent_2 

inqtextextent2 

inquire text_extent_3 

inqtextextentS 

inquirejtext_index 

inqtextindex 

inquire_valuator 

inqvaluator 

inquire^view_jdepth 

inqview depth 

inquire_view_plane_distance 

inqview planedist 

inquire .view_plane_normal 

inqviewplanenorm 

inquire_view_reference_point 

inqviewrefpoint 

inquire_view_up_2 

inqview up2 

inquire_view_up_3 

inqview up3 

inqnire_viewing_control, pajameters 

inqvw gcntrlparms 

inquire_vie'wing_paramcters 

inqview ingparams 

inquire_viewport_2 

inqview port2 

inquire^viewportjS 

inqview port3 

inquirejvisibility 

inqvisibility 

inquire_w indow 

inqwindow 

inquir ejw orldjc oordin at e_m atrix_2 

inqworldmatrix 2 

inquir e_w orld_c oordin at e jn atrixJS 

inqworldmatrixS 

!ine_abs_2 

lineabs2 

line absjS 

lineabs3 

linejrel_2 

linerel2 

linejrel_3 

linerelS 

map_ndc_to_world_2 

mapndctoworld2 

m ap_ndc^to_w orld_3 

mapndctow orldS 

map_world_to_ndc_2 

mapworldtondc2 

m ap_worldjto_ndc J5 

mapworldtondc3 

marker ab8_2 

markerabs2 

marker ab8_3 

markerabs3 

marker_rel_2 

markerrel2 

marker_rel_3 

markerrel3 

move abs 2 

moveabs2 

move absjS 

moveab83 

move_rel_2 

moverel2 

move_rel_3 

moverelS 

new_frame 

new frame 

polygon_abs_2 

polygonabs2 

polygon_abs_3 

polygonabsS 

poIygon_rel_2 

polygonrel2 
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Correspondence Between O Names and Pascal Names 

SunCore Name 

Pascal Equivalent 

polygonjrcIJS 

polygonrelS 

polyline_abs_2 

polyline_ab8_3 

polylincjreL2 

polyline_rel_3 

polyniarker_ab8_2 

polylineabs2 

polylineabs3 

polylinerel2 

polylinerelS 

polymarkerabs2 

polymarker_abs_3 
polyniarker_rel_2 
polymarkerjrel_3 
printjerror 
putjraster 

polym arkerabsS 
polymarkerrel2 
polym arkerrelS 
printerror 
putraster 

rastcrjtojle 

rename_retainedjsegment 

report_|no8t_jecent_error 

restorejiegment 

ssvejsegment 

rastertofile 

renameretainseg 

reportrecenterr 

restoresegment 

8avesegment 

selcctjricwjsurfacc 

8et_b&ck_plane_clipping 

set_charju8t 

8etjcharpath_2 

8et_charpath_3 

selectvwsurf 

setbackclip 

setcharjust 

setcharpath2 

setcharpathS 

setjcharprecision 

8et_char8i£e 

set.charepace 

8etjcharup_2 

8et_charup_3 

setcharprecision 

setcharsize 

setcharspace 

setchanip2 

setcharupS 

8et_coordinate_8y8temjtype 

setjdetectability 

setjdrag 

8et_echo 

8et_echo_group 

setcoordsystype 

setdetectability 

setdrag 

setecho 

setechogroup 

set_echo_position 

setjechojsurface 

8ct_fill_index 

set^font 

8et_front_plane_clipping 

setechoposition 

setecbosurface 

setfillindex 

setfont 

setfrontclip 

set.highlighting 

8et_image_transformation_2 

sethighlighting 
set imgtr ansform 2 
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Correspondence Between C Names and Pascal Names 

SunCore Name 

Pascal Equivalent 

set_im age_tr ansform ation_3 
set_image_transformation_type 
set _image_,tran8late_2 

setimgtran3form3 

setimgxformtype 

8etimgtranslate2 

set_image_translate_3 

setjceyboard 

8etJight_direction 

aetjinejndex 

setjinestyle 

setimgtranslateS 

setkeyboard 

setlightdirect 

aetlineindex 

setlinestyle 

setjinewidth 

setJocator_2 

8et_marker_8ymbol 

8etjndc_space_2 

8et_ndc_8p ace_3 

setlinewidth 

8etlocator2 

setmarkersymbol 

setndcspace2 

setndcspaceS 

8et_output_clipping 

8et_pen 

set^pick^id 

8et_polygon_edge_style 

8et_poIygon_interior_style 

setoutputclip 

aetpen 

setpickid 

setpolyedgestyle 

setpolyintrstyle 

8et_primitive_attributes 

set_projection 

setjrasterop 

set_8egment_detectab!lity 

set.segmentjbighlighting 

setprimattribs 

setprojection 

setrasterop 

setsegdetectable 

setseghighlight 

set jsegmentjm age^ransformationJJ 
setjjegmentJmagejtransformationjS 
setjsegmentjm agejtr ans lateJ2 
8etjsegmentJmagc_tran*latej3 
8et_8egment_vi8ibility 

setsegimgxform2 

setsegimgxfonnS 

8etsegimgxlate2 

setsegimgxlateS 

setsegvisibility 

set shading parameters 

setjstroke 

setjtextjndex 

set_valuator 

set_vertex_indice5 

setshadingparams 

setstroke 

settextindex 

setvaluator 

setvertexindices 

set_vertex_normals 

8et_view_depth 

set_view_plane_distance 

8et_view_pIane_normal 

set_viewj’eference_point 

set vertex norm als 
setviewdepth 
setview planedist 
setviewplanenorm 
setviewrefpoint 
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Correspondence Between C Names and Pascal Names 

SunCore Name 

Pascal Equivalent 

set_view_up_2 

setviewup2 

8et_view_up_3 

setviewupS 

set_viewing_parameters 

setviewingparams 

set_viewport_2 

set view port2 

8et_viewport_3 

set view port3 

set_visibility 

setvisibility 

8et_window 

setwindow 

set_window_clipping 

set window clip 

8ctjworldjeoordinate_matrix_2 

setworldmatr ix 2 

setjw orld_coordinate_p» atrix_3 

setworldmatrix3 

set_8buffer_cut 

setzbuffercut 

8ite_faster 

sizeraster 

terminate_core 

terminatecore 

terminate_device 

terminatedevice 

terminatc_vicw_8urface 

terminatevwsurf 

text 

puttext 
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D.5. declarations for SunCore-Pascal Interface 



D.5.1. Type Declarations 

type iaiT = arpay(l..256] of integer; 

type parr = array[1..256] of real; 

type cct “ array[1..257] of char; 

type ivarray = array[1..4,l-4] of real; 

type ivarray 1 = array[1..3,l-3] of real; 

type pttype = record 
x,y,z,w:real; 
end; 

type aspect — record 

width, height:real; 
end; 

type primattr = record 
lineindx: integer; 
fillindx: integer; 
textindx: integer; 
linestyl: integer; 
polyintstyl: Integer; 
polyedgstyl: integer; 
linwidth: real; 
pen: integer; 
font: integer; 
charsize: aspect; 
chrup, chrpath, chrspace: pttype; 
chjust: integer; 
chqualty: integer; 
marker: integer; 
pickid: integer; 
rasterop: integer; 
end; 
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type rasttyp =» record 

width: integer; 
height: integer; 
depth: integer; 
bits: integer; {var} 
end; 

type cmap = record 

typ: integer; 
nbyt: integer; 
dat :integer; {var} 
end; 

type windtypc =* record 

xmin, xmax, ymin, ymax:real; 

end; 

type port-type =» record 

xmin,xmax,ymin,ymax,Kmin,£max:real; 

end; 

type vwprmtype record 

vwrefpt: array [1..3] of real; 
vwplnorm: array [1..3] of real; 
viewdi8:real; 
frontdi8:real; 
backdi3:real; 
projtype:integer; 
projdir: array [1..3] of real; 
window:windtype; 
vwupdir: array (1..3] of real; 
viewport'.porttype; 
end; 

type vwsurf = record 

screenname: array [1..DEVNAMESIZE) of char; 

windowname: array [1..DEVNAMESIZE] of char; 

windowfd:integer; 

dd: integer; 

instance:integer; 

cmapsize:integer; 

cmapname: array [1..DEVNAMESIZE] of char; 

flag8:integer; 

ptr: integer; 

end; 

type vwsurfst = array [l..DEVNAMESIZEj of char; 
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type vwarr = array [1..MAXVSURF] of vwsurf; 

c 



o 
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D.5.2. Function Declarations 


function allocatera8ter(var rptr:rastt 7 p):!nt^er; external; 

function a'waitanybutton(tim:integer; 

var buttonnum;integer):integer; external; 

function awtbuttongetloc2(time:integer; locatomumdnteger; 

var buttonnum:integer; var x:real; 
var y:real):integer; external; 

function awtbuttongetyal(time:integer; valnumiinteger; 

var buttonnum:integer; var vahreal): 
integer; external; 

function awaitkeyboard(tim:Integer;keynttm;integer;var sptrxct; 

var length:integer):integer; external; 

function awaitpick(time:integer; picknuminteger; 

var segnamiinteger; var pickid:integer) 

:integer; external; 

function a'wait8troke2(tim:integer;picknum:lnteger;asize;integer;var x:parr; 

var y:parr;numxy:lnteger):integer; external; 

function beginbatehupdatednteger; external; 

function cIoseretainBegdnteger; external; 

function closetempsegdnteger; external; 

function createretainseg(8egname:integer):integer; external; 

function createtempsegdnteger; external; 

function defcoIorindices(surfacename:ywsurf; 

il:lnteger;i2:integer; 

var r:parr;var g:parr;var b:parr 

):{nteger; external; 

function delallretainsegsinteger; external; 

function delret!unsegment(segname:integer):integer; external; 

function deselcctvwsurf(surfacename:rw8urf 
):integer; external; 

function endbatchupdatednteger; external; 

function filepas(fname;cct;sw:tnteger;fileid:integer):integer; externai; 
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function filetorastei^rasfidrintegerjvar rptr:rasttyp; 

var map:cmap):integer; external; 

function freerastei(var rptr:rasttyp);integer; external; 

function getmousestate(var x:real;var y:real;var buttonsanteger): 
integer; external; 

function getrastei(sttrfacename :vwsurf; 

xmin:real;xmax:real;ymin:real;ymax:roaI; 
xd:lnteger;yd:integer;var rptr:ra8ttyp):integer; 
external; 

function inttialiEecore(outputleyel:integer; 

inputleveldnteger; 

dimension:integer):integer; external; 

function initializedevice(deviceclass:lnteger; 

devicenum:integer):integer; external; 

function initializevwsurf(8urfacename:vw8urf; typdnteger 
) integer; external; 

function inqcharjust(var chjuflt:lnteger):integer; external; 

function inqcharpath2(var x:real;var y:real):integer; external; 

function inqcharpath3(var x:real;var y:real;var z:real):integer; external; 

function inqcharpreci8ion(var chquality:integer):integer; external; 

function inqchar8ize(var width:real;var height;real):integer; external; 

function inqchsa'8pace(var space:real):integer; external; 

function inqcharup2(var x:real;var y:real):integer; external; 

function inqcharup3(var x:real;var y;real;var z;real):integer; external; 

function inqcolorindices(surfacename:vw8urf; 

il:integer;i2:integer; 

var r:parr;var g:parr;var b:parT 

):integer; external; 

function inqcuiTpos2(var x:real;var y:real):integer; external; 
function inqcurrpos3(var x:real;var y:real;var z:real):integer; external; 
function inqdetectability(var detect:integer):integer; external; 
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function inqecho(deycIass:lnteger;<leTnum:integer; 

vnr echotypeinteger):integer; external; 

function inqechopo8ition(deTcla88:integer;deynum:integer; 

var x:real;var y:real):integer; external; 

function inqechosurface(deTcIa8s:integer;deTnum:lnteger; 

var surfacename:vw8urf):integer; external; 

function inqfilUndex(var color:lnteger):lnteger; external; 

function mq^ont(var font:lnteger):integer; external; 

function inqhighli^ting(var lughlight:lnteger):integer; external; 

function inqimgtran8fonn2(var 8x:real; var sy:real;var atreal 

;var tx:real; var ty:real 
):integer; external; 

function inqimgtran8form3(var 8x:real; var 8y:real;var 8z:real 

;var ax:real; var ay:real;var asireal 
;var tx:real; var ty:real;var tz:real 
):integer; external; 

function inqimgxformt 3 rpe(var 8egtype:lnteger):integer; external; 

function inqimgtran8late2(var tx:real; var ty:real):integer; external; 

function inqimgtran8late3(var tx:real; var ty:real;var tz:real 

):integer; external; 

function inqinycompmatrix(var iarray:iyarray):integer; external; 

function inqkeyboard(keynum:inieger;var bufsize:integer;var stringxct; 

var po8:integer):integer; external; 

function inqlineindex(var coior:lnteger):integer; external; 

function inqnne8tyle(var nne8tyle:integer):Integer; external; 

function inqUnewidth(var liuewidtb:real):integer; externai; 

function inqIoeator2(locnuininteger; 

var x:real;var y:real):integer; external; 

function inqmarkersymboI(var mark:integer):integer; external; 

function inqiidcspace2(var width:real;var height:real):integer; external; 
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function inqndcspace3(var widthirealjvar height:real;var 
depth:real):integer; external; 

function inqopenretainseg(var 8egname:integer):integer; external; 

function inqopent33iipseg(var open:integer):integcr; external; 

function inqpen(var pen:integer):integer; external; 

function inqpickid(var pick:integer):integer; external; 

function inqpolyedgestyle(var pe 3 tyle:integer):integer; external; 

function inqpolyintrstyle(var pistyle:intcger):integer; external; 

function inqpTimattribs(var defprim:primattr):integer; external; 

function mqprojectioii(var ptypeunteger; var dx:real; var dy:real; 

var dz:real):integer; external; 

function inqrasterop(var rastop:integer):integer; external; 

function incpetainsegname(arraycnt:integer; var seglist:iarr; 

var segcnt;integer):integer; external; 

function inqretainsegsurf(segname:integer; arraycntdnteger; var surflist:vwarr; 

var 8urfciit:integer):integer; external; 

Note: oince vwarr ia an array of MAXVSURF viewawfaeea, arrayent ahould be MAXVSURF. 

function iiiqsegdetectable(segnameinteger;var dtablerinteger) 
integer; external; 

function mqseghighlight(3egnaine:integer;var highlightdnteger) 
integer; external; 

function inqsegimgxform2(segname:integer;var 8x:real;var sy:real; 
var a:real;var tx:real;var ty:real 
):integer; external; 

function inqsegimgxform3(segname:integer;var sx:real;var 8y:real; 

var sz:real;var rx:real;var ry:real; 

var Tz:real;var tx:real;var ty:real;var tzireal 

):integer; external; 

function inqsegimgxfrmtyp(segname:integer;var segtype:integer) 
integer; external; 

function inqse^mgx!ate2(segname:integer;var tx:real;var ty:real) 
integer; external; 
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function in(isegimgxlate3(segname:integer;var sx:real;var sycreal; 

var st:real):integer; external; 

function in(^egvisibility(segname;integer;var visible:integer): 
integer; external; 

function mqstroke(strokenum:integer;var bufsize:integer;var 
dist:real;var time:integer):integer; external; 

function inqtextextent2(var string:cct;var <lx:real; var dyireal 

):integer; external; 

function inqtextextent3(var string:cct;var dx:real; var dyrreal 

; var dz:real):integer; external; 

function inqtextindex(var color:integer):integer; external; 

function inqvaluatoi(Talnum:integer;var init:real;var low:real;var highireal) 

integer; external; 

function inqTiewdepth(var fdi9t:real;var bdistireal) 

integer; external; 

function inqviewplanedi8t(var vdist:real):integer; external; 

function inqviewplanenorm(var dxrreal; var dy:real; 

var dz:real):integer; external; 

function inqyiewrefpoint(var rx:real; var ryrreal; 

var rK:real):integer; external; 

function inqviewup2(var dx:real; var dy:real 

):integer; external; 

function mqyiewup3(var dx:real; var dyireal; 

var dz:real):integer; external; 

function inqywgcntrlpm‘ins(var wclip:integer;var fclipdnteger; 

var bclip:integer;var typ:integer) 
integer; external; 

function inqyic'wmgparams(var viewparm:vwprmtype):lnteger; external; 

function inqviewport2(var xminireal; var xmax:real;var ymm:real;var ymaxrreal 

):integer; external; 

function inqyie'wport3(var xmin:real; var xmax:real;var ymiii:real;var ymax:real 

;var zmin:real;var zmax:real) 
anteger; external; 
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function inqvisibility(var visibie:integer) 
integer; external; 

function inqwindow(var umin:real; var umax;peal;var vmin:real;var Tmax:real 

):integer; external; 

function inqworldmatrix2(var iarray:ivarrayl);integer; external; 

function inqworIdmatrix3(var iarray:ivarray):integer; external; 

function lineabs2(x:real;y:real);integer; external; 

function Iineabs3(x:real;y:real;z:real):integer; external; 

function linere]2(x:real;y:real}:integer; external; 

function linerel3(x:real;y:real;z:real):integer; external; 

function mapndctoworld2(ndx:real; ndytreal; 

var wldx:real; var wldy:real) 
integer; external; 

function mapndctoworld3(ndx:real; ndyrreal; ndz:real; 

var wldx:real; var wtdy:real 
; var wldz:real) 
rinteger; external; 

function mapworldtondc2(wldx:real; widyrreal; 

var ndxireal; var ndy:real) 
nnteger; external; 

function mapworldtondc3(wldx:real; wldy:real; wldz:real; 

var ndx;real; var ndy:real 
; var ndzrreal 

):integer; external; 

function markerabs2(mx:real;my:real);integer; external; 
function markerabs3(mx:real; my:real;mz:real):integer; external; 
function markerrel2(dx:real;dy:real):integer; external; 
function markerret3(dx:real; dy:real;dz:real):integer; external; 
function moyeabs2(x:real;y:real);integer; external; 
function moyeabs3(x:real;y:real;z:real):integer; external; 
function moyeTel2(x:real;y:real):integer; external; 
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function moyerel3(x:real;y:real;z:re&l):integer; external; 

function newframe:integer; external; 

function pasloc(function f:integer 
):integer; external; 

function polygonabs2(var xcoor:parr; var ycoor:parr; 
n:integer):integer; external; 

function poIygonab83(var xcoor:parr; var ycoor:parr;var zcoor:parr; 
n:integer):integer; external; 

function polygonrel2(var xcoor:parr; var ycoorrparr; 
n:integer):integer; external; 

function polygonrel3(var xcoor:parr; var ycoor:parr;var zcoor:parr; 
n:integer):integer; external; 

function polylineabs2(var xcoor:parr; var ycoor:parr; 
n:integer):integer; external; 

function polylincabs3(var xcoor:parr; var ycoor:parr;var zcoorrparr; 
n:integer):integer; external; 

function polyIinerel2(var xcoor:parr;var ycoor:parr; 
n:integer):integer; external; 

function polyIinereI3(var xcoor:parr; var ycoor:parr;var zcoor:pvr; 

n:integer):integer; external; 

function polymarkerabs2(var xcoorrparr; var ycoor:parr; 
n:integer):Integer; external; 

function polymarkerab83(var xcoor:parr; var ycoor;parr;var zcoorrparr; 
ii:integer):integer; external; 

function polymarkerrel2(var xcoorrparr; var ycoorrparr; 
n:integer):integer; external; 

function polymarkerrel3(var xcoorrparr; var ycoor;parr;var zcoorrparr; 
n:integer):integer; external; 

function printerror(var 8tring:cct;eiTorrintcger)rinteger; external; 
function putrastcr(var rptrrrasttyp)rinteger; external; 
function puttext(var stringrcct)rinteger; external; 


Revision E of 7 January 1984 


D-21 





Using SunCore with Pascal Programs 


SunCore Reference Manual 


function rastertofile(var rptr:rasttyp;var map:cmap;rasfid:integer 

):iuteger; external; 

function renameretainseg(segname:integer;newname:integer):integer; external; 

function reportrecenterr(var error:integer):mteger; external; 

function restoresegment(segname:integer;var fname:cct):integcr; external; 

function savesegment(segname:integer;var fname:cct):integer; external; 

function selectvwsurf(3urfacename:vwsiuf 
):integer; external; 

function 8etbackcHp(oEoff:intcger):integer; external; 

function 8etcharju8t(chjust:integer):lnteger; external; 

function setcharpath2(dx:peal; dy:real):integer; external; 

function setcharpath3(dx:real; dy:peal;dz:peal):integep; external; 

function setcharprecision(chquality:integer):lntegep; external; 

function setcharsize(chwid:real;chht:real):integer; external; 

function setcharspace(space:real):integer; external; 

function setcharup2(dx:real; dy:real):integep; external; 

function setcharup3(dx:peal; dy:real;dz:rcal):integep; external; 

function 8etcoordsystype(typ:integer):integer; external; 

function 8etdetectability(detect:integer);integer; external; 

function setdrag(drag:integer):integer; external; 

function setecho(devcla9s:integer;devnum:integer; 

echotype:integer):integer; external; 

function setechogroup(devclass:integer;var devarray:iarr;n:lnteger; 
echotype:integer) integer; external; 

fun ction setechoposition(devc lass:integer;devnum dnteger; 
x:real;y:real):integer; ecternal; 

function setecho3urface(devclass:integep;deYnum:integer; 
surfacename:vwsurf):integep; external; 

function setfillindex(color:integer):integer; external; 
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function setfont(font:integer):integer; external; 

function setfrontclip(ono£f:mteger):integer; external; 

function sethighlighting(highlight:intcgcr):integer; external; 

function setimgtransform2(8x:real; sy:real;a:real 

;tx:real; ty;real);5nteger; external; 

function 8ctimgtransform3(8x:real; sy:real;sz:real; 

ax:real; ay:real;az:real; 
tx;real; ty:real;tz:real) 

:integer; external; 

function 8etimgxforintype(8egtype:integcr);integer; external; 

function setimgtranslate2(tx:real; ty:real):integer; external; 

function 8etimgtranslate3(tx:real; ty:real;tz:reai):integer; external; 

function 8etkcyboard(keynum:integer;buf8ize:integer;var 8tring:cct; 

po8:integer):integer; external; 

function 8etlightdirect{dx:real; dy:real;dz:real 

):integer; external; 

function 8etlineindex(color:integer):integer; external; 

function setlme8tyle(8tyte:integer):integer; external; 

function setlibe'width(width:real):integer; external; 

function 8etlocator2(Iociium;!nteger;x:rcal;y:real):integer; external; 

function 8etmarker8ymbol(mark:integer):integer; external; 

function sctndcBpace2(widtb:real;heigbt:real):integer; external; 

function setndcspace3{width:rcal;height:real;depth:real) 

dnteger; external; 

function 8etoutputcUp(ottoff;integer):integer; external; 
function setpen(pen:integer):integer; external; 
function setpickid(pickid:integer):integer; external; 
function 8etpolyedgestyIe(pestyle:integer):integer; external; 
function 8etpolyiiitrstyIe(pistyle:integer):lnteger; external; 
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function 8etprimattribs(var defprim:primattr):integer; external; 

function setprojection(ptype:integer;dx:real; dy:real;dz:real) 

integer; external; 

function setrasterop{rop:integer):integer; external; 

function setsegdetectable(9egname:integer; detectbhinteger) 

integer; external; 

function setseghighlight(segname:integer; highlight integer) 

integer; external; 

function setsegimgxforin2(segname:integer;sx:real; 8y:real;a:real; 

tx:real;ty:real):integer; external; 

function 8etsegimgxform3(segname:integer; sx:real; 8y:real; 

sz;real; rx:real; ry:real; rz:real 
; tx:real; ty:real; tz:real 
):integer; external; 

function 8et8egimgxlate2(8egnameinteger;tx:real; ty:real 

):integer; external; 

function set9e^ingxlate3(segname:integer;tx:real; ty:real;tz:real 

):integer; external; 

function setsegvisibility(segname:integer;yisible:integer);integer; external; 

function 8etshadingparams(amb:real;dif;real;8pec:real;flood:real; 

bump:real;hue:integer;9tyle:integer 
);integer; external; 

function setstroke(8trokenum:integer;buf8ize:integer; 
dist:real;time:integer) 
integer; external; 

function settextindex(color:integer):integer; external; 

function setvaluator(valnum:integer;init:real;low:real;high:real) 
rinteger; external; 

function setyertexindices(var x:iarr;n:integer):integer; external; 

function setvertexnormals^var xcoor:parr; var ycoor:parr;var zcooripair; 
n;integer):!nteger; external; 

function 8etviewdepth(near:real;f’ar:real):integer; external; 

function setyiewplanedist(di3t:real):integer; external; 


D-24 


Revision E of 7 January 1984 







SunCore Reference Manual 


Using SunCore with Pascal Programs 


function 8etylewplaiienorm(dx:real; dj:real;dz:real):integer; external; 

function setviewrefpoint(x:real; y:real;z:real):integer; external; 

function 8etviewup2(dx:real; dy:real):integer; external; 

function setviewup3(dx:real; dy:real;dz:real):integer; external; 

function 8etviewingparams(var viewparm:vwprmtype):integer; external; 

function 8etvtewport2(xmin;real;xmax:real;ymin:real;ymax:real): 
integer; external; 

function 3etviewport3(xmin:real;xmax:real;ymin:real;ymax;real;zmm:real;zmax:real) 

unteger; external; 

function setTi8ibility(Ti8ibility:integer):lnteger; external; 

function 8etwindow(umin;reaI;umax:real;vinin:real;Ymax:real) 
integer; external; 

function 8etwindowclip(onoff:integer):integer; external; 
function 8etworldmatrix2(var tarray:iTarrayl):integer; external; 
function setworldmatrix3(var iarray:ivarray):integer; external; 

function 8etzbuffercut(var surfacename:TWsurf;var x:parr;var z:parr;ii:integer):integer; exterly 

function 8izera8ter(var 8urfacename:vwsuTf; 

xmin:real;xmax:real;ymin;real;ymax:real; 
var rptr:rasttyp);integer; external; 

function terminatecore.'integer; external; 

function tenninatedevice(deTclass:{nteger;devnum:integer):integer; external; 
function tennmatevw8UTf(var 8urfacename:yw8urf):lnteger; external; 
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Appendix E 


Higher Performance SunCore Library 


SunCore programs which are to be run on machines with Sun’s hardware floating point option 
may use an alternative SunCore library which provides higher floating point performance. 
This library is in /uir//t6//tfrepre«%.a. A program linked with this library will only run on a 
machine with hardware floating point. 

To use this library for C programs, use a C compiler command line like: 

% ce -faky --o grab grab.e —Icoreaky -launwindow —Iplxreet -Im 
and to use tUs library for Fortran programs: 

% f77 '-faky -o grab grab.f -Icore77 ->lcore8ky -bunwindow -Ipixrect -Im 

Note that this library cannot be used with Pascal programs in the current release. 

If compiling and linking are done in separate steps, the -faky option must also be specified in 
the linking stage. The -faky option may also be used in the compiling step. See the c(;(l) and 
/77(1} manual pages for details. 
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Translatable 3-D, 4-2 
initializejcore, 2-2 
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pick, 7-1 
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stroke, 7-1 
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inquire_8egment.Iughlighting, 8-24 
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8-25 

inquirejsegmenOmagejtransformationJS, 

8-25 

inquire_8egment_image_tran8formationjtype, 

6-17 

inquire^segmenOmagejtransIateJl, 8-25 
inquirejsegment_image_tran8latej3, 8-25 
inquirejsegment.visibility, 8-24 
inquirejstroke, 7-13 
inquire_text_jextent_2j 

inqiiire_text_cxtent_3, 5-8 
inquire_text_index, 8-13 
inquire_valuator, 7-12 
inquirejrisibility, 8-23 
keyboard input device 
echoing, 7-3,7-1 
Line Routines, 5-5 
Iine_abs_2, 5-5 
line_abs_3, 5-5 
lincjrel_2, 5-5 
linejreljS, 5-5 
lint library, 1-6 
locator input device 
echoing, 7-4,7-1 
Marker Functions, 5-9 
marker_abs_2, 5-9 
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markcr^absJS, 5-9 
markerjel_2, 5-9 
markerjrel_3, 6-10 
move_abs_2, 6-2 
move_abs_3, 6-3 
move_jeL2, 6-4 
movejeljS, 6-4 
moving functions, 5-2 
naming, 4-1 
ncw_frame, 2-6 

normalized device coordinates, 1-0 
output primitives 
line, 6-1 
marker, 6-1 
move, 6-1 
polygon, 5-1 
polylinip, 5-1 
polymarker, 6-1 
rasters, 6-1 
text, 5-1 

output Primitives, 5-1 
pick input device 
echoing, 7-3,7-1 
picture change control, 2-1 
pixwindd view surface, B-2 
polygon shading parameters, 5-11 
polygonjabs_2, 6-14 
polygon_ab8_3, 6-14 
polygon_jel_2, 6-14 
polygonjreLS, 6-14 
Polyline Routines, 5-0 
polyline_abs_2, 6-0 
polyline_abs_3, 5-0 
polyIine_ycl_2, 5-7 
polyIinej«l_3, 6-7 
polymarker_abs_2, 6-10 
polymarkerjabsJ3, 6-10 
polymarkcr_reI_2, 5-10 
polymarkerjreljS, 5-11 
primitive attributes, 0-1 
primitive static attributes 
charjust, 0-3 
charpath, 0-2 
charprecision, 0-3 
charsize, 0-2 
charspace, 0-3 
charup, 0-2 


fill index, 0-1 
font, 0-2 
line index, 6-1 
linestyle, 0-1 
linewidth, 0-2 
markerjsymbol, 0-3 
pen, 0-2 
pickjd, 0-3 
polygon edge style, 0-2 
polygon interior style, 0-2 
rasterop, 0-3 
text index, 0-1 
put^raster, 5-15 
Raster Functions, 6-16 
raster_to_file, 5-17 
reading 

input devices, 7-8 
rcnamejretainedjsegment, 4-4 
report_mo8tjrecent_eiTor, 2-6 
restorejsegment, 4-0 
retained segment, 4-1 
retained segment attributes, 4-1 
retained segment dynamic attributes, 4-1 
Retained Segment Dynamic Attributes, 0-17 
retained segment static attributes, 4-1 
Retained Segment Static Attributes, 0-10 
sampled input devices, 7-1 
savejsegment, 4-0 
segment attributes, 0-1 
segmentation, 4-1 
segment^ 
retained, 4-1 
temporary, 4-1 , 4-1 
8elect_view_surface, 2-3 
setjcharjust, 0-10 
8et_charpath_2, 0-10 
set_chjurpath_3, 0-10 
8et_charprecision, O-ll 
8et_charsize, 0-9 
setjcharspace, 0-9 
set_charup_2, 0-9 
set_charup_3, 6-10 
setjdetect ability, 6-18 
setjdrag, 2-5 
setjecho, 7-0 
set echo .group, 7-6 
8et_echo_position, 7-6 
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set_echo_surface, 7-6 

set_fiILindex, 6-7 

setjfont, 6-9 

8et_highlighting, 6-18 

8et„imagejbransformatton_2, 6-19 

8eOmagejbransformatioii_3, 6-20 

8et_imagejtransformation_type, 6-17 

8etJmagejbransIate_2, 6-19 

8Ct_imagejbran8latej3, 6-19 

set^keyboard, 7-7 

setjightjdipection, 5-12 

setjinejndex, 6-7 

setjinestyle, 6-8 

set_linewidth, 6-8 

8et_locator_2, 7-7 

setjmarkerjsymbol, 6-11 

8et_pick_id, 6-11 

set_polygon_edge_8tyle, 6-8 

8et_polygon_iiiteriorjstyle, 6-8 

8et_priinitive_attribute8, 6-11 

sttjraaterop, 6-11 

aetjiegmentjdetcctability, 6-20 

setjicgmcntJiighHghtiiig, 6-20 

set_8egmenOmagejtran8formatioii_2, 6-21 

8etjiegmeiit_image_tran8forination_3, 6-22 

8eOegmentJimagc_tran8lat.e_2, 6-21 

8etj5egment_imageJbraU8late^3, 6-21 

8Ct_8egment_visibility, 6-20 

8Ct_shading_paraiiieter8, 5-11 

setjstroke, 7-8 

8et_text_index, 6-7 

set_valuator, 7-7 

8et^vertex_indices, 5-12 

set_vertex_normals, 5-12 

set_visibility, 6-18 

8et_zbu£fcr_cut, 5-13 

shading 

CONSTANT, 5-11 
GOURAUD, 5-11 
PHONG, 5-11 
shading parameters, 5-11 
sizejraster, 5-16 
static attributes, 6-1 
stroke input device 
echoing, 7-4,7-1 
SunCore 
using, 1-7 


temporary segment, 4-1 
terminate_core, 2-2 
terminate_device, 7-2 
terminate_view_8urface, 2-3 
terminating 

input devices, 7-2 
text, 5-7 

Text Routines, 5-7 
texture 
black, 6-6 
cross hatched, 6-6 
grey tone, 6-6 
hatched left, 6-6 
hatched right, 6-6 
wallpaper, 6-6 
wavy lines, 6-6 
white, 6-6,6-3 

three-dimensional polygon, 5-11 
valuator input device 
echoing, 7-5,7-1 
view surface 
initializing, 2-2 
selecting, 2-2,2-2 
view surface control, 2-1 
view surface types 
bwldd, B-2 
bw2dd, B-2 
cgldd, B-2 
cgpixwindd, B-3 
pixwindd, B-2 
view stuiaces, B-1 
view volumes, 3-1 
vwsurf structure, B-1 
wallpaper texture, 6-6 
wavy lines texture, 6-6 
white texture, 6-6 
windows, 3-1 
world coordinates, 1-6 
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READER COMMENT SHEET 


Dear Customer, 

We who work here at Sun Microsystems wish to provide the best possible documentation for 
our products. To this end, we solicit your comments on this manual. We would appreciate 
your telling us about errors in the content of the manual, and about any material which you 
feel should be there but isn’t. 


Typographical Errors: 

Please list typographical Errors by page number and actual text of the error. 


o 

Technical Errors: 

Please list errors of fact by page number and actual text of the error. 


Content: 

Did this guide meet your needs! If not, please indicate what you think should be 
added or deleted in order to do so. Please comment on any material which you feel 
should be present but is not. Is there material which is in other manuals, but would be 
more, convenient if it were in this manual? 


Layout and Style: 

Did you find the organization of this guide useful? If not, how would you rearrange 
things? Do you find the style of this manual pleasing or irritating? What would you 
like to see different? 


o 



o 



o 
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